| name | go-microservice-guardrails |
| description | 将 Go 微服务架构规范应用到代码生成、重构整改和规范评审中。适用于涉及 gRPC、proto、contracts、services/、pkg/、服务边界、接口所有权、配置边界、数据最小权限、服务间鉴权、可观测性、部署与测试的任务。 |
Go 微服务架构规范
概览
在处理 Go 微服务任务时,先用这份 Skill 约束架构边界,再进入具体实现。目标不是教 Go 语法,而是确保生成、整改、评审都遵守同一套服务边界、契约所有权、配置边界、最小权限和可观测性规则。
任务归类
先判断当前任务属于哪一类,再决定读哪些 reference:
生成:新建服务、补 proto、补共享基础设施、补部署或测试骨架
整改:目录重构、收敛配置、拆边界、修正通信或权限模型
评审:检查设计、目录、契约、代码或部署测试是否违反规范
如果任务同时涉及多个主题,优先按“边界与所有权 -> 契约 -> 通信鉴权 -> 配置与共享包 -> 数据权限与部署测试 -> 可观测性”的顺序处理。
Reference 导航
按任务主题读取对应 reference,不要一次性加载全部文件:
- 涉及工作区结构、模块落位、根目录职责时,读
references/repository-layout.md
- 涉及 proto、Buf、生成代码、接口归属时,读
references/contracts-and-codegen.md
- 涉及 gRPC metadata、服务身份、用户上下文透传和逐跳授权时,读
references/service-communication-auth.md
- 涉及
internal/config、pkg/ 边界和共享基础设施抽取时,读 references/config-and-shared-pkg-boundaries.md
- 涉及服务自治、接口所有权和跨服务依赖时,读
references/service-boundaries.md
- 涉及数据拥有权、运行时账号、跨服务数据访问时,读
references/data-min-privilege.md
- 涉及数据库约束、联调资源、Docker 构建和测试分层时,读
references/database-deploy-test.md
- 涉及日志、Trace、缓存刷新、配置或密钥热更新时,读
references/observability-hot-reload.md
固定执行顺序
所有任务都先做边界判断,再做实现判断:
- 确认服务边界和接口所有权是否正确
- 确认契约真源、生成路径和字段归属是否正确
- 确认服务间通信、服务认证和用户上下文透传是否正确
- 确认配置是否留在服务内、共享包是否只承载无业务语义能力
- 确认数据访问、运行时权限、部署资源和测试落位是否正确
- 最后才讨论具体代码、目录、部署细节和测试实现
如果前面的边界判断不成立,不要直接开始写代码补丁。
三类任务的输出方式
生成
- 先给出符合规范的目录与职责划分
- 再给契约位置、生成路径、服务间依赖和测试落位
- 最后才给最小实现骨架
整改
- 先明确违反了哪条规范
- 说明风险来自哪里
- 按最小改动原则给出修正方案
评审
- 以问题清单优先
- 每个问题明确对应的规范主题
- 明确风险、影响范围和建议整改方向
输出要求
输出中始终说明:
- 本次用了哪些 reference
- 哪些结论是从已有代码或文档直接得出的
- 哪些结论属于基于规范的推断
如果上下文不足以判断某个边界,应明确列为待确认项,不要把猜测写成既成事实。
硬性禁止项
- 不允许把共享 proto 真源放进服务目录
- 不允许把服务私有配置、领域模型或服务私有鉴权流程抽到
pkg/
- 不允许服务依赖其他服务的内部实现、内部数据结构或仓储实现
- 不允许服务通过运行时 DSN 直接修改其他服务拥有的数据边界
- 不允许把
x-service-token、x-user-id、x-user-authenticated 混进业务 request
- 不允许在业务 handler 中直接读取原始 metadata 作为可信身份
- 不允许把上游服务签发的服务令牌原样转发给下游
- 不允许热更新、缓存刷新、配置切换失败时没有日志、Trace 或回退策略
默认工作方式
当用户要求“按规范生成”“按规范整改”“检查是否符合微服务规范”时:
- 先给出当前任务对应的规范主题
- 明确哪些目录、接口、配置或权限边界必须先收敛
- 再输出实现建议、代码结构或评审结论
如果只是普通 Go 语法、算法题、CLI 小工具或与微服务架构无关的任务,不要使用这份 Skill。