拓冰网站定制 
Macro数据库规则CS-01到CS-38深度解读资深Rust工程师的DB哲学【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址: https://gitcode.com/GitHub_Trending/macro3/macroMacro是一个面向团队的统一工作区邮件、聊天、文档、任务、AI Agent、通话与 CRM 全部通过 引用串联并共享一套 AI 记忆。支撑这套复杂系统的是一套写进代码库的军规——本文带你逐条解读Macro 数据库规则 CS-01 到 CS-38看懂资深 Rust 工程师藏在这些规则背后的 DB 哲学。️CS 规则是什么一分钟看懂规则体系这些规则全部定义在 docs/STYLE_GUIDE.md 中是整个项目代码评审的单一事实来源。每条规则只占一行格式统一为规则ID [作用域] 规则内容 (证据 · 强制手段 · 文档)。ID 前缀区分技术栈前缀范围CS-##Rust 后端crates/、services/、tooling/FE-##前端与共享 TypeScriptapps/web、packages/CS 规则按作用域分成 10 个标签[db]数据库与迁移、[types]类型设计、[cfg]配置与环境、[err]错误与可观测性、[arch]架构边界、[api]API 设计、[sec]安全与权限、[rust]Rust 惯用法、[perf]性能、[test]测试。规则 ID 永久稳定——评审时可以引用见 CS-30规则只增不删、永不重编号。删除会留空号新规则用下一个空闲数字追加。这让规则库像法律条文一样可追溯。CS-01CS-09数据库九条铁律DB 哲学核心区这 9 条是全文最精华的部分几乎每条都来自真实踩坑括号中的 # 号即 PR 编号。CS-01 · ID 必须在应用层生成 UUIDv7永远不要用数据库的gen_random_uuid()那是不可排序的 UUIDv4。UUIDv7 天然按创建时间排序主键扫描即时间线。在迁移文件 20260831172113_user_api_key_id_name_hash.sql 中就能看到注释直接引用 CS-01把规则钉在代码旁边。CS-02 · 一切可能竞争的插入都要幂等种子数据、回填脚本一律带ON CONFLICT处理——重跑一万次数据库状态不变。CS-03 · 优先自然键/复合键如果一张表本来就按业务列查询排序就别再造一个代理 ID。REST 路由也直接用自然 ID。CS-04 · 用户列统一叫user_id拒绝owner_user_id、author_id这类创造性命名跟随既有表的约定。CS-05 · 级联删除必须有剧本新表上线前就要想清楚删除 A 时挂在它下面的 B、C 怎么办不许把这件事留给数据库默认行为。CS-06 · 拒绝冗余索引主键前缀已经覆盖的列不需要再单独建索引——多出来的索引只会拖慢写入。CS-07 · 别存上下文里已有的列租户级已固定的 scoping id 再存一份就是纯粹的垃圾数据。CS-08 · 默认使用编译期校验查询sqlx::query!/query_as!是默认选项SQL 写错直接编译失败裸query只留给真正无法静态化的动态查询。配套工作流详见 docs/DATABASE_DEVELOPMENT.md。CS-09 ·.sqlx缓存只在仓库根目录统一用nix develop --command just prepare_db刷新绝不允许单个 crate 私藏一份缓存——缓存漂移是团队协作的头号杀手。CS-10CS-13类型设计哲学CS-10ID 和 Token 一律 newtype 包装构造时校验格式杜绝到处飞的裸 String。CS-11封闭字符串集合就是枚举不是 String。CS-12可空就用OptionT不许用哨兵值表达没有。CS-13三态数据未加载 / 缺失 / 有值用一个扁平枚举表达而不是层层嵌套的 Option。CS-14CS-18配置与环境的快速失败CS-14规定所有环境变量必须走macro_env_var/macro_config共享 crate禁止手写std::env::var——配置入口唯一化clippy 直接封禁裸调用。CS-15要求配置在服务启动时就校验完缺环境变量应该杀死进程而不是杀死某个请求。这两条合起来就是快速失败哲学的落地。CS-16CS-18 则细化到错误上下文、Doppler 密钥命名一致性等运维细节。CS-19CS-22错误与可观测性CS-19第三方错误必须有自己的错误变体别把 JWT 解析失败塌缩成内部错误——排障时你需要的正是那个具体来源。CS-20要求依赖限流的外部服务商时必须备好后路降级模型、重试或文档化的降级路径。CS-21强调用量计量要覆盖每一条调用路径包括 MCP 触发的工具调用。CS-22规范 tracing 埋点Result函数必须带err字段错误用结构化字段记录。CS-23CS-29架构边界——控制巨石生长这组规则直接回应代码库如何不腐化CS-23禁止继续膨胀macro_db_client——新领域逻辑必须开新 crate通吃型 crate 只能收缩。CS-24单文件超过约 1000 行就拆分别等评审员开口。CS-25mod.rs只声明子模块不承载逻辑。CS-26先复用再重写——大概率已存在的逻辑服务客户端、权限检查、OAuth 工具必须找到并复用。CS-27共享领域表只能由属主 crate 读写其他地方禁止裸 SQL。CS-28别急着把一次性代码抽成共享 crate依赖方向必须指向通用。CS-29泛滥的根目录文件如 Dockerfile归入专门目录。CS-30CS-35API 与处理层设计CS-30要求 Axum handler 通过State注入共享服务而非Extensionast-grep 规则自动拦截违规写法。CS-31强调横切服务挂到属主领域服务上而不是随手挂在路由层。CS-32CS-35则约束模型一致性新增 API 模型必须镜像既有模型的形状、兄弟端点共用同一 DTO 并一起迁移、泛型抽象要设计成T → U而不是T → T。CS-36CS-38安全与权限——最小权限三连CS-36权限授予必须是无状态 HTTP 端点而不是内存信道消息——因为断线重连后内存流就丢了。CS-37向下游传递数据时签发窄作用域 Token而不是转发用户完整 JWT。最小权限靠结构实现而非靠自觉。CS-38工具Tool响应必须是消息链的合法成员携带tool_call_id与链元数据——在多 Agent 场景下消息链完整性就是安全边界。如何落地just check单一门禁规则不是挂在墙上的标语而是可执行的质量门在项目根目录运行just check会对你的变更执行 格式化 lint 代码规则检查每条发现都以文件:行号 [规则ID]输出并附上修复命令。just check full额外加上 tsc 与 clippy。配合 docs/DATABASE_DEVELOPMENT.md 中的数据库开发流程迁移必须用 SQLx 生成、迁移先于服务部署、删列走两阶段这套 CS 规则构成了一个闭环规则 → 自动检查 → 评审引用 → 持续沉淀新规则。总结DB 哲学三句话数据库是共享契约——迁移必须兼容已部署代码幂等优先级联要有剧本CS-01CS-09。类型系统是最好的防御——把非法状态变成编译错误而不是运行时事故CS-08、CS-10CS-13。架构靠规则防腐——属主制、快速失败、最小权限让十年后的代码库依然可读CS-15、CS-23、CS-37。这套规则的价值不只属于数据库工程师任何参与 Macro 贡献的开发者都能从中学到如何写出让别人放心的代码。【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址: https://gitcode.com/GitHub_Trending/macro3/macro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Macro数据库规则CS-01到CS-38深度解读：资深Rust工程师的DB哲学
Macro数据库规则CS-01到CS-38深度解读资深Rust工程师的DB哲学【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址: https://gitcode.com/GitHub_Trending/macro3/macroMacro是一个面向团队的统一工作区邮件、聊天、文档、任务、AI Agent、通话与 CRM 全部通过 引用串联并共享一套 AI 记忆。支撑这套复杂系统的是一套写进代码库的军规——本文带你逐条解读Macro 数据库规则 CS-01 到 CS-38看懂资深 Rust 工程师藏在这些规则背后的 DB 哲学。️CS 规则是什么一分钟看懂规则体系这些规则全部定义在 docs/STYLE_GUIDE.md 中是整个项目代码评审的单一事实来源。每条规则只占一行格式统一为规则ID [作用域] 规则内容 (证据 · 强制手段 · 文档)。ID 前缀区分技术栈前缀范围CS-##Rust 后端crates/、services/、tooling/FE-##前端与共享 TypeScriptapps/web、packages/CS 规则按作用域分成 10 个标签[db]数据库与迁移、[types]类型设计、[cfg]配置与环境、[err]错误与可观测性、[arch]架构边界、[api]API 设计、[sec]安全与权限、[rust]Rust 惯用法、[perf]性能、[test]测试。规则 ID 永久稳定——评审时可以引用见 CS-30规则只增不删、永不重编号。删除会留空号新规则用下一个空闲数字追加。这让规则库像法律条文一样可追溯。CS-01CS-09数据库九条铁律DB 哲学核心区这 9 条是全文最精华的部分几乎每条都来自真实踩坑括号中的 # 号即 PR 编号。CS-01 · ID 必须在应用层生成 UUIDv7永远不要用数据库的gen_random_uuid()那是不可排序的 UUIDv4。UUIDv7 天然按创建时间排序主键扫描即时间线。在迁移文件 20260831172113_user_api_key_id_name_hash.sql 中就能看到注释直接引用 CS-01把规则钉在代码旁边。CS-02 · 一切可能竞争的插入都要幂等种子数据、回填脚本一律带ON CONFLICT处理——重跑一万次数据库状态不变。CS-03 · 优先自然键/复合键如果一张表本来就按业务列查询排序就别再造一个代理 ID。REST 路由也直接用自然 ID。CS-04 · 用户列统一叫user_id拒绝owner_user_id、author_id这类创造性命名跟随既有表的约定。CS-05 · 级联删除必须有剧本新表上线前就要想清楚删除 A 时挂在它下面的 B、C 怎么办不许把这件事留给数据库默认行为。CS-06 · 拒绝冗余索引主键前缀已经覆盖的列不需要再单独建索引——多出来的索引只会拖慢写入。CS-07 · 别存上下文里已有的列租户级已固定的 scoping id 再存一份就是纯粹的垃圾数据。CS-08 · 默认使用编译期校验查询sqlx::query!/query_as!是默认选项SQL 写错直接编译失败裸query只留给真正无法静态化的动态查询。配套工作流详见 docs/DATABASE_DEVELOPMENT.md。CS-09 ·.sqlx缓存只在仓库根目录统一用nix develop --command just prepare_db刷新绝不允许单个 crate 私藏一份缓存——缓存漂移是团队协作的头号杀手。CS-10CS-13类型设计哲学CS-10ID 和 Token 一律 newtype 包装构造时校验格式杜绝到处飞的裸 String。CS-11封闭字符串集合就是枚举不是 String。CS-12可空就用OptionT不许用哨兵值表达没有。CS-13三态数据未加载 / 缺失 / 有值用一个扁平枚举表达而不是层层嵌套的 Option。CS-14CS-18配置与环境的快速失败CS-14规定所有环境变量必须走macro_env_var/macro_config共享 crate禁止手写std::env::var——配置入口唯一化clippy 直接封禁裸调用。CS-15要求配置在服务启动时就校验完缺环境变量应该杀死进程而不是杀死某个请求。这两条合起来就是快速失败哲学的落地。CS-16CS-18 则细化到错误上下文、Doppler 密钥命名一致性等运维细节。CS-19CS-22错误与可观测性CS-19第三方错误必须有自己的错误变体别把 JWT 解析失败塌缩成内部错误——排障时你需要的正是那个具体来源。CS-20要求依赖限流的外部服务商时必须备好后路降级模型、重试或文档化的降级路径。CS-21强调用量计量要覆盖每一条调用路径包括 MCP 触发的工具调用。CS-22规范 tracing 埋点Result函数必须带err字段错误用结构化字段记录。CS-23CS-29架构边界——控制巨石生长这组规则直接回应代码库如何不腐化CS-23禁止继续膨胀macro_db_client——新领域逻辑必须开新 crate通吃型 crate 只能收缩。CS-24单文件超过约 1000 行就拆分别等评审员开口。CS-25mod.rs只声明子模块不承载逻辑。CS-26先复用再重写——大概率已存在的逻辑服务客户端、权限检查、OAuth 工具必须找到并复用。CS-27共享领域表只能由属主 crate 读写其他地方禁止裸 SQL。CS-28别急着把一次性代码抽成共享 crate依赖方向必须指向通用。CS-29泛滥的根目录文件如 Dockerfile归入专门目录。CS-30CS-35API 与处理层设计CS-30要求 Axum handler 通过State注入共享服务而非Extensionast-grep 规则自动拦截违规写法。CS-31强调横切服务挂到属主领域服务上而不是随手挂在路由层。CS-32CS-35则约束模型一致性新增 API 模型必须镜像既有模型的形状、兄弟端点共用同一 DTO 并一起迁移、泛型抽象要设计成T → U而不是T → T。CS-36CS-38安全与权限——最小权限三连CS-36权限授予必须是无状态 HTTP 端点而不是内存信道消息——因为断线重连后内存流就丢了。CS-37向下游传递数据时签发窄作用域 Token而不是转发用户完整 JWT。最小权限靠结构实现而非靠自觉。CS-38工具Tool响应必须是消息链的合法成员携带tool_call_id与链元数据——在多 Agent 场景下消息链完整性就是安全边界。如何落地just check单一门禁规则不是挂在墙上的标语而是可执行的质量门在项目根目录运行just check会对你的变更执行 格式化 lint 代码规则检查每条发现都以文件:行号 [规则ID]输出并附上修复命令。just check full额外加上 tsc 与 clippy。配合 docs/DATABASE_DEVELOPMENT.md 中的数据库开发流程迁移必须用 SQLx 生成、迁移先于服务部署、删列走两阶段这套 CS 规则构成了一个闭环规则 → 自动检查 → 评审引用 → 持续沉淀新规则。总结DB 哲学三句话数据库是共享契约——迁移必须兼容已部署代码幂等优先级联要有剧本CS-01CS-09。类型系统是最好的防御——把非法状态变成编译错误而不是运行时事故CS-08、CS-10CS-13。架构靠规则防腐——属主制、快速失败、最小权限让十年后的代码库依然可读CS-15、CS-23、CS-37。这套规则的价值不只属于数据库工程师任何参与 Macro 贡献的开发者都能从中学到如何写出让别人放心的代码。【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址: https://gitcode.com/GitHub_Trending/macro3/macro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考