Macro代码规范CS/FE规则集解析：200+条Code Review风格指南-创锋一号

Macro代码规范CS/FE规则集解析：200+条Code Review风格指南

【免费下载链接】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

Macro 是一个集成邮件、聊天、文档、任务、AI Agent、通话与 CRM 的统一团队工作区，所有信息通过 @-链接互通。它的开源仓库里藏着一份极其完整的Macro 代码规范：按 CS（Rust 后端）/ FE（前端）双轨编号的 Code Review 风格指南，配合自动化质量门禁形成 200+ 检查点的质量矩阵。本文带你完整读懂这套规则集的设计思路。

![Macro统一团队工作区产品概览，邮件聊天文档任务与AI Agent一体化](https://raw.gitcode.com/GitHub_Trending/macro3/macro/raw/1ed220be5023f90f8140e19e9169800e56594f8d/.github/readme/Hero Image from Figma.png?utm_source=gitcode_repo_files)

📌 CS/FE 双轨编号：一套可引用的规则体系

风格指南 docs/STYLE_GUIDE.md 中的每条规则都遵循统一格式：

<规则ID> [作用域标签] 规则说明 (证据 · 执行手段 · 关联文档)

规则集	覆盖范围	编号示例
CS-##	Rust 后端（`crates/`、`services/`、`tooling/`）	CS-01、CS-30、CS-55
FE-##	前端与共享 TypeScript（`apps/web`、`packages/`）	FE-01、FE-25、FE-33

两个值得借鉴的设计细节：

ID 永不重排：评审时可以直接写“见 CS-30”“FE-25”，规则删除后留下空号而不是回填——规则集因此成为一份可长期引用的“坐标系”。
作用域标签可 grep：CS 用[db][types][cfg][err][arch][api][sec][rust][perf][test]十个标签；FE 用[data][solid][async][arch][ts][ui]六个标签，一条命令即可捞出某个领域下的全部约定。

🦀 55 条 CS 规则：Rust 后端评审要点

CS 规则集覆盖从数据库到 AI 遥测的 55 条约定。下面是 Code Review 中最常出现的几条：

规则	一句话解读
CS-01	ID 在应用代码里生成 UUIDv7——v7 天然按创建时间排序，禁用数据库`gen_random_uuid()`
CS-08	默认使用编译期检查的`sqlx::query!`，由 clippy`disallowed-methods`直接拦截非宏写法
CS-14	环境访问一律走`macro_env_var`/`macro_config`，禁止`std::env::var`
CS-15	快速失败——缺环境变量应该在服务启动时就终止，而不是拖到请求内部
CS-24	源文件控制在约 1000 行以内，在评审人开口之前就拆好
CS-26	先复用再实现——服务客户端、权限检查、oauth 工具先找现成的，别写第二份
CS-30	Axum handler 通过`State`拿共享服务，不用`Extension`（ast-grep 强制执行）
CS-41	用`#[expect(..., reason)]`替代`#[allow(...)]`——lint 失效时`expect`会报警
CS-51	领域层不出现 AWS/redis/reqwest 等基础设施——六边形架构，依赖只允许指向内层

CS-01 至 CS-09 清一色[db]标签，与 docs/DATABASE_DEVELOPMENT.md 的工作流一一对应，改动数据库前建议先读它。

⚡ 33 条 FE 规则：SolidJS 前端约定

FE 规则集覆盖数据获取、SolidJS 响应式、异步与 UI 约定四大板块，精选如下：

规则	一句话解读
FE-01	UI 代码禁止直接调用 service client——取数一律走`queries`包缓存层，避免重复请求
FE-08	不搞临时全局状态模块，共享状态挂在清晰所有权边界的 Context 上
FE-10	`createEffect`只用于外部/命令式系统（DOM、三方库）——派生状态请用派生信号
FE-21	禁用`any`，用正经类型或`unknown`+ 类型守卫
FE-25	用语义化颜色 token，不用裸 Tailwind 调色板——默认调色板已被禁用，`text-red-500`会静默失效
FE-33	新功能采用分层 feature 架构，以`features/activity`为参考实现

其中 FE-33 展开为完整的 docs/FRONTEND_FEATURE_ARCHITECTURE.md：core/放纯类型与函数、queries/放 wire 适配器、primitives/放无 JSX 响应式状态、components/放纯 props 表现组件、views/放用例组合——这是前端模块化的可执行蓝图。

🛡️ 规则如何被机器强制执行：just check 四层门禁

Macro 代码规范最实用的地方在于：规则不只是给人看的，而是被机器执行的。本地门禁只有一个命令just check（定义见 tooling/just/check.just）：

范围限定——只检查相对origin/main变更过的文件，历史代码的问题永远不会干扰你
快速模式——just check秒级跑完 rustfmt + biome + oxlint + ast-grep
完整模式——just check full追加 tsc + clippy（-Dwarnings -Dclippy::disallowed_methods）
可读输出——所有结果以file:line [规则ID]打印，并附上修复命令

背后是四层强制工具：

ast-grep：rules/ast-grep/ 下 25 个规则文件，AST 级匹配代码模式。例如 rust-no-axum-extension-param.yml 就是 CS-30 的执法者，文件note里直接回链规则编号
clippy：clippy.toml 用disallowed-methods拉黑std::env::var、sqlx::query等，并写明一条换法理由
oxlint：落地 FE-12 的promise/prefer-await-to-then，.then()/.catch()链无处遁形
biome：TS/TSX 格式化 + lint，参数与 CI 完全一致

🚀 新手参与贡献：三步上手规则集

克隆并准备环境：git clone https://gitcode.com/GitHub_Trending/macro3/macro，按 docs/RUNNING_LOCALLY.md 完成本地搭建（只改前端可不搭本地栈）。
提交前先自检：跑just check；改过 SQL 就先just prepare_db刷新 sqlx 缓存；受影响包用cargo test -p <crate>验证。
PR 里引用规则号：评审人习惯直接写“见 CS-30 / FE-25”，分支与 PR 标题采用 Conventional Commits 命名（如feat(chat): ...），完整流程见 CONTRIBUTING.md。

仓库还配有 AGENTS.md 作为 AI 编码代理的入口指南，前端细节在 apps/web/AGENTS.md——这套规则集本身也是“人机共读”的文档。

✅ 总结

Macro 代码规范规则集的最大特色：每条规则都有稳定编号、作用域标签和机器执行路径。55 条 CS 规则 + 33 条 FE 规则，叠加 25 个 ast-grep 规则文件与 clippy / oxlint / biome 多重强制层，最终由just check一条命令收敛成本地质量门禁。无论你是想参与贡献，还是想借鉴工程实践，都值得通读一遍 docs/STYLE_GUIDE.md——这本质上是一份被压缩成 88 行的完整 Code Review 方法论。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析