代码维护边界
1分钟内可阅读完
文件归属
| 类别 | 例子 | 修改方式 |
|---|---|---|
| CLI 托管文件 | 带 Code generated by "grpc-kit-cli/...". DO NOT EDIT. 的启动/注册/关闭代码与脚本 | 通过 CLI 模板与项目迁移更新 |
| 协议生成文件 | *.pb.go、*_grpc.pb.go、*.pb.gw.go、Swagger | 修改 Proto/YAML，再生成 |
| ent 生成文件 | modeler/ent 中的生成实现 | 修改 schema/*.go，再生成 |
| 用户扩展文件 | handler/private.go、业务 RPC handler、业务配置和 schema | 在项目内维护与测试 |
最终以文件标记和当前模板为准，不依据目录名猜测。不要手改生成文件修复业务行为。迁移命令只处理符合证据规则的已有托管文件。
扩展入口
privateExtended 注入业务依赖；privateUnaryServerInterceptor 与 privateStreamServerInterceptor 扩展 RPC interceptor；privateHTTPHandle 注册原生 HTTP；privateMCPHandle 注册 MCP 资源。原生 HTTP/MCP handler 不应默认被视为已经过业务 RPC 鉴权。
微单体的领域模块应公开服务接口并隐藏内部模型，避免跨域直接访问其他模块的 ent 表。共享工具层不导入上层业务、Admin 或配置装配；依赖在启动入口显式注入。拆分时首先移动领域实现，再保持契约兼容，不把跨域数据库访问作为长期集成接口。
AI 辅助开发
CLI 模板带有 .agents/skills/add-api-domain/SKILL.md，其流程围绕 Proto、Gateway/OpenAPI、生成、handler 与测试。使用前阅读项目内实际技能版本，并检查允许编辑的文件范围。技能帮助执行开发流程，不自动建立模块隔离。
每次修改先明确契约与文件归属，再审阅生成 diff，运行单测、构建与黑盒 E2E。涉及身份、数据删除和工具调用时补充越权与失败场景测试，不能把 AI 生成代码或迁移成功输出当作验证结果。