规范不是两本文档
前端规范和后端规范常被分开写，但它们解决的是同一个问题：多人协作下如何稳定交付。前端更靠近用户体验、状态管理、组件复用和构建产物；后端更靠近业务规则、数据一致性、权限、安全和可观测性。
好的团队规范应该有统一语气和统一门槛。比如“必须、应该、禁止”需要在两端含义一致；分支、提交、评审、测试也应该使用同一套流程承接。
- 前端负责页面结构、交互状态、组件边界和构建质量。
- 后端负责接口契约、业务流程、事务边界和数据安全。
- 共同部分包括 Git、提交、评审、CI、发布和事故复盘。
- 规范要能被检查工具承载，而不是只靠口头提醒。
前端侧的检查重点
前端规范要避免只写目录结构。真正影响交付质量的是组件职责是否清楚、接口错误态是否完整、移动端是否可用、可访问性是否基本达标，以及构建产物是否稳定。
对于业务后台，前端不应该做得像营销页。它需要密度、扫描效率、表单容错、列表筛选、批量操作和权限态处理。组件抽象也应该围绕真实业务重复，而不是为了抽象而抽象。
- 路由、状态、请求、权限、表单和表格要有固定模式。
- 按钮、输入框、弹窗、空状态和错误态要统一。
- 移动端导航不能直接消失，至少要有菜单入口。
- 构建前跑 lint、type-check 和 build。
后端侧的检查重点
后端规范的核心是把变化放到合适位置。Controller 不承载复杂流程，Business 表达业务动作，DAO 收敛数据访问。配置读取、Migration、SQL 参数绑定、异常处理和日志埋点，是后端规范里最容易影响线上稳定性的部分。
当团队能用同一套质量门禁检查前后端时，规范才真正进入工程系统。否则它只是文档。
- Controller 只处理协议、校验和响应。
- Business 负责规则、流程、事务和跨 DAO 编排。
- DAO 负责查询、写入和参数绑定。
- 数据库结构变化必须走 Migration 并能回滚。
共同语言：必须、应该、绝不
知识库里的前后端规范都使用规则强度来表达要求，这一点非常重要。团队协作最怕同一句话在不同人那里强度不同。“必须”代表违反就不能合并，“应该”代表默认遵守但可说明例外，“绝不”代表高风险红线。
这种表达方式让规范从建议变成契约。它也方便代码评审时减少情绪：评审不是某个人挑剔，而是对照共同约定。
- 必须：安全、数据一致性、构建通过、接口契约。
- 应该：命名、组件边界、目录组织、错误态完整。
- 绝不：拼接 SQL、提交密钥、跳过权限、直接改生产配置。
- 例外情况必须在 PR 中说明原因和后续处理。
前端规范的核心不是 UI 好看
前端规范在知识库里覆盖命名、目录、HTML/CSS/TS、组件职责、API 层收敛、可访问性、兼容性和性能。对于业务系统，前端的核心目标不是把页面做得热闹，而是让重复操作稳定、清晰、少出错。
这意味着表格筛选、批量操作、权限态、空状态、错误提示、加载态和移动端导航都要被当成一等功能。
- API 请求集中封装，避免组件里到处拼接口。
- 表单字段、校验、提交态和错误态要统一。
- 权限按钮隐藏之外，也要考虑禁用态和解释文案。
- 移动端不能把导航直接隐藏到不可访问。
后端规范的核心是数据和流程可信
后端规范更关注 Controller-Business-DAO 分层、配置读取、SQL 注入防护、Migration 管理和环境映射。后端一旦出错，影响的不只是页面体验，而是数据、权限和资金口径。
所以后端规范往往更强调边界：业务逻辑不要塞进 Controller，配置不要直接 env，数据库变更不要手改，SQL 不要拼接。
- Controller 面向协议，不承载长流程。
- Business 面向业务动作，承接事务和规则。
- DAO 面向数据域，统一查询与写入。
- Migration 让表结构变化可追溯、可评审、可回滚。
把规范落到 CI，而不是贴在墙上
如果规范不能被工具检查，它最终会退化成口号。前端可以用 ESLint、TypeScript、测试和构建兜底；后端可以用语法检查、测试、静态分析、迁移检查和接口冒烟兜底。共同部分则由 Git 分支、提交规范和 PR 模板承接。
规范的成熟标志不是文档越来越长，而是人工提醒越来越少。
- PR 模板检查需求、测试、影响范围、回滚方案。
- CI 失败自动阻止合并。
- 发布记录绑定分支、提交和环境。
- 事故复盘反向更新规范和门禁。