本文档由 g2rain-infra 的 docs/development/code-conventions.md 自动同步生成。

# 代码规范

分层

• 固定依赖方向为 startup → biz → api。
• API 只放稳定查询/发号契约、DTO、VO 和枚举。
• Controller 负责协议、参数校验和结果包装；领域规则、事务和事件位于 Service。
• DAO 只负责持久化；PO 不作为接口响应；转换优先使用 MapStruct。

写入与并发

• 多步写入使用 @Transactional，但不能把消息发布误认为本地事务的一部分。
• “先查再写”必须有数据库唯一键兜底。
• 号段最大值必须由数据库原子更新，修改双缓冲、步长或锁时补充并发测试。
• Snowflake 租约失效、时钟回拨或 Worker ID 获取失败时必须拒绝发号。

日志与安全

• 使用统一日志，不输出密码、Token、数据库/Nacos/Redis 凭据或完整敏感载荷。
• 写接口依赖可信主体与授权；不能只因为位于内网就视为安全。
• 配置通过环境变量、Nacos 或 Secret 注入，不在 Java 中硬编码环境值。

文档

公共 API、数据库、事件类型、发号算法、配置和运行边界变化时，同步更新对应文档或 ADR。