go-microservice-guardrails

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

固定执行顺序

所有任务都先做边界判断，再做实现判断：

1. 确认服务边界和接口所有权是否正确
2. 确认契约真源、生成路径和字段归属是否正确
3. 确认服务间通信、服务认证和用户上下文透传是否正确
4. 确认配置是否留在服务内、共享包是否只承载无业务语义能力
5. 确认数据访问、运行时权限、部署资源和测试落位是否正确
6. 最后才讨论具体代码、目录、部署细节和测试实现

如果前面的边界判断不成立，不要直接开始写代码补丁。

三类任务的输出方式

生成

• 先给出符合规范的目录与职责划分
• 再给契约位置、生成路径、服务间依赖和测试落位
• 最后才给最小实现骨架

整改

• 先明确违反了哪条规范
• 说明风险来自哪里
• 按最小改动原则给出修正方案

评审

• 以问题清单优先
• 每个问题明确对应的规范主题
• 明确风险、影响范围和建议整改方向

输出要求

输出中始终说明：

• 本次用了哪些 reference
• 哪些结论是从已有代码或文档直接得出的
• 哪些结论属于基于规范的推断

如果上下文不足以判断某个边界，应明确列为待确认项，不要把猜测写成既成事实。

硬性禁止项

• 不允许把共享 proto 真源放进服务目录
• 不允许把服务私有配置、领域模型或服务私有鉴权流程抽到 pkg/
• 不允许服务依赖其他服务的内部实现、内部数据结构或仓储实现
• 不允许服务通过运行时 DSN 直接修改其他服务拥有的数据边界
• 不允许把 x-service-token、x-user-id、x-user-authenticated 混进业务 request
• 不允许在业务 handler 中直接读取原始 metadata 作为可信身份
• 不允许把上游服务签发的服务令牌原样转发给下游
• 不允许热更新、缓存刷新、配置切换失败时没有日志、Trace 或回退策略

默认工作方式

当用户要求“按规范生成”“按规范整改”“检查是否符合微服务规范”时：

1. 先给出当前任务对应的规范主题
2. 明确哪些目录、接口、配置或权限边界必须先收敛
3. 再输出实现建议、代码结构或评审结论

如果只是普通 Go 语法、算法题、CLI 小工具或与微服务架构无关的任务，不要使用这份 Skill。