工程标准

StackRivet 的工程标准不是只活在 wiki 里的风格指南——它们被编码进 AI 护栏、ArchUnit 测试和 CI 门禁，所以违反即构建失败。本页概括治理代码库的标准；项目随代码一起发布完整的工程标准、架构治理和代码评审文档。

不变量

分层

• Controller → Service → Domain → Mapper，只能单向——绝不跨层。
• 实体永不越过持久化边界；用 DTO 和 VO。

安全

• 默认拒绝；每个受保护端点声明 @PreAuthorize。
• 不存明文密码；密码 / token / 密钥 / 验证码不进日志。
• 私有文件每个 signed URL 前都先做权限校验。

数据

• 所有结构变更走 Flyway——不手改生产库。
• 每个列表 API 分页，pageSize 最大 200；sort 用白名单。
• 表用 sr_ 前缀和标准列。

异步与文件

• 重任务（导入、导出、生成器写入）作为异步任务运行，带 idempotencyKey、重试、错误分类、超时。
• Asset Service 是唯一文件系统；业务表存 asset_id，绝不存 URL。

前端

• 用 StackRivet 设计系统；绝不交付默认 Element Plus 观感。

流程

• 新业务模块走生成器，不手搓。
• 每个 commit 有可复现的 Verified: 行——不用模糊措辞。
• 分支寿命 ≤ 3 天；PR ≤ 500 行代码。

依赖纪律

同一类问题一种默认写法，且保持窄的依赖面：

• 框架优先。 先用 JDK 21 内建，再用 Spring 自带工具，再用成熟领域库——然后才考虑新增。窄而精的工具库只在前者确实不够时引入，逐个论证。
• 禁百宝箱工具库。 包罗万象的”工具箱”库（如 Hutool）被 Maven enforcer 拒绝——它们助长零散、难审计的用法。手写加密、编码、集合工具同样是反模式。
• 禁反射式 bean 拷贝。 DTO/VO 映射显式手写（或编译期生成），字段改名或缺失会编译报错，而非静默错配。
• 每个依赖都过许可证审查。 因为 StackRivet 有商业 Enterprise 版和私有部署，copyleft（GPL / AGPL）不能进默认发行物——优先 Apache-2.0 / MIT / BSD，每个选型 ADR 都记录许可证。

CI 门禁

合并主分支至少跑：

1. 后端格式检查、单元测试、集成测试
2. 数据库迁移验证
3. 代码生成器快照测试
4. 前端 lint、typecheck、单元测试
5. Playwright E2E
6. Docker Compose 冒烟测试
7. ArchUnit（或等价）架构边界测试
8. CLI doctor 冒烟测试

发布额外加 JDK 25 前瞻兼容、MySQL 9.7 冒烟、真实阿里云 OSS 往返、CodeQL（或等价）和 SBOM / 签名发布检查。

原则

小团队和 AI 工具无法被指望去记住纪律，所以 StackRivet 把纪律变成会运行的东西：会失败的测试、会拦截的门禁、AI 必须读的规则。这正是让生成代码和手写代码保持同一标准的关键。