# 后端应用代码规范（工程执行版）

> 适用栈：Node.js / Java / Python / Go / Rust 等服务端应用。语言细则仍需同时遵守对应规范。

## 1. 分层边界（强制）

- 路由 / Controller 层只做协议适配：认证上下文、参数读取、参数校验、响应包装。
- Application / Service 层负责编排业务用例、事务边界、权限校验、领域服务调用。
- Domain 层承载业务规则、状态流转、领域校验，不依赖 HTTP、数据库、消息队列等基础设施。
- Repository / DAO 层只封装持久化访问，不承载业务判断。
- Infrastructure 层封装外部系统、缓存、消息队列、对象存储、邮件短信等适配器。
- 禁止跨层直连：Controller 不直接访问数据库，Domain 不直接调用 HTTP client 或读取环境变量。

## 2. API 契约

- 对外 API 必须明确路径、方法、请求 DTO、响应 DTO、状态码、错误码与鉴权要求。
- API 版本化策略必须稳定：破坏性变更使用新版本或兼容迁移字段。
- 请求参数必须在进入业务层前校验类型、必填、范围、枚举、长度、格式。
- 响应结构必须统一，业务错误与系统错误不得混用成功响应。
- 列表接口必须支持分页并设置默认值与最大上限；排序、过滤字段必须白名单化。
- 创建、支付、回调、消息消费等重复触发风险场景必须设计幂等键或唯一约束。

## 3. 业务逻辑与事务

- 一个 Service 方法只对应一个清晰用例，避免把多个独立业务流程堆在同一方法。
- 事务边界放在用例层，覆盖一次业务一致性所需的最小写操作范围。
- 事务内禁止执行不可控耗时外部调用；必须调用时应有超时、补偿或异步化设计。
- 多步写操作必须定义失败回滚、补偿或最终一致性方案。
- 并发修改必须使用数据库唯一约束、乐观锁、悲观锁或分布式锁之一，不依赖前端防重。
- 状态机类业务必须显式校验当前状态与目标状态，禁止隐式覆盖。

## 4. 数据访问

- SQL / NoSQL 查询必须参数化或通过 ORM / Query Builder 构造，禁止拼接用户输入。
- 高频查询字段、唯一业务键、外键关联字段应建立索引，并在迁移脚本中留痕。
- ORM 关联查询必须评估 N+1 风险，必要时使用批量查询、预加载或显式 join。
- 数据模型与 API DTO 分离，禁止把数据库实体直接作为对外响应。
- 软删除、审计字段、租户字段、数据权限字段必须在 Repository 或查询构造层统一处理。
- 数据迁移脚本必须可重复执行或具备明确前置检查，失败后可定位与回滚。

## 5. 错误处理与日志

- 统一错误模型必须区分参数错误、鉴权错误、权限错误、资源不存在、业务冲突、系统异常。
- 全局异常处理必须兜底，客户端响应不得暴露堆栈、SQL、密钥、内部路径。
- 错误信息必须包含可定位上下文：模块、用例、字段、资源 id、requestId / traceId。
- 日志使用结构化格式，关键操作记录 actor、action、resource、result、requestId / traceId。
- 日志级别必须稳定：预期业务失败使用 warn / info，非预期异常使用 error。
- 密码、token、身份证、手机号、邮箱、银行卡等敏感字段必须脱敏或禁止进入日志。

## 6. 安全基线

- 所有受保护接口必须经过认证，敏感操作必须做资源级授权校验。
- 多租户系统必须在查询和写入路径统一校验租户边界，禁止只依赖客户端传参。
- CORS、CSRF、Cookie、Session、JWT、OAuth 等安全配置必须按部署形态显式配置。
- 密码必须使用 BCrypt、Argon2 或等价算法哈希存储，禁止明文或可逆加密存储。
- 密钥、数据库连接串、第三方凭证必须来自环境变量或密钥管理系统，禁止硬编码。
- 文件上传必须校验类型、大小、扩展名、存储路径和访问权限。
- 对登录、验证码、导出、批量操作、昂贵查询等接口设置限流或频控。

## 7. 外部依赖与异步任务

- 外部 HTTP / RPC 调用必须设置超时、重试策略和错误映射，不允许无限等待。
- 重试必须只用于可重试错误，并结合幂等设计避免重复副作用。
- 消息生产必须明确 topic / routing key、消息 schema、幂等键和失败处理。
- 消息消费必须支持重复投递，处理失败进入重试、死信或人工补偿流程。
- 定时任务必须防并发重入，关键任务记录执行开始、结束、耗时和结果。
- 缓存必须定义 key 规则、TTL、失效策略和一致性边界，禁止把缓存当作唯一事实来源。

## 8. 可运维性与测试

- 服务必须提供健康检查，至少区分进程存活与关键依赖可用性。
- 应用启动时校验必需配置，缺失配置必须快速失败并输出可定位错误。
- 服务必须支持优雅关闭，停止接收新请求并释放数据库、消息队列、HTTP 连接等资源。
- 关键指标应可观测：请求耗时、错误率、外部调用耗时、队列积压、任务失败数。
- 新增接口至少覆盖成功路径、参数失败路径、权限失败路径或业务失败路径。
- 涉及数据库、缓存、消息队列、外部系统适配时，优先补集成测试或契约测试。
- 高风险变更（事务、权限、计费、数据迁移、并发）必须补回归用例。