Claude Code 在 SaaS 后端 API 开发中的 4 层结构落地与 3 类质量校验实践

1. 四层结构不是分层架构图，而是上下文隔离的物理边界

大多数人第一次在 SaaS 后端项目里用 Claude Code 写 API，会直接丢一个POST /users的需求进去，让它“生成完整控制器”。结果拿到的代码里混着数据库查询、DTO 转换、业务校验、甚至硬编码了 Redis key。这不是 AI 不行，是它根本没被赋予清晰的职责边界——就像让一个刚入职的应届生同时写接口、写 SQL、写缓存策略、写单元测试，还要求他记住上周三你提过的那个字段命名偏好。

我们团队在交付三个 SaaS 产品（含一个日活 80 万的 B2B 工具）后，把 Claude Code 的协作方式从“写代码”升级为“共建结构”。核心动作不是调 prompt，而是用文件系统和目录约定强行切出四层物理隔离区：api/、service/、domain/、infra/。这四层不是 Spring Boot 默认的包结构，而是 Claude Code 理解上下文的最小单位。它不会跨层推理——你让它改service/UserService.java，它绝不会去动infra/RedisConfig.java，除非你显式把后者加进上下文。

这个设计直接解决了“上下文丢失”这个高频坑点。Claude Code 的上下文窗口不是无限的，当项目超过 50 个 Java 类时，它的记忆衰减曲线非常陡峭。而四层结构相当于给它配了四个独立的“工作台”：API 层只放 HTTP 协议相关逻辑（参数解析、状态码、OpenAPI 注释），Service