用途:Gram 管理 API 是支撑其控制台、CLI 和 SDK 的内部 HTTP-RPC 接口,用于管理项目、工具集(toolsets)、部署、访问控制及相关资源。每个端点位于 /rpc/<service>.<method>,使用 Goa DSL 在 server/design/ 下编写,在 server/internal/<service>/ 下以每个包一个 Service 结构体实现,并通过生成的服务器桩、OpenAPI、CLI 绑定和 TypeScript SDK 对外暴露。
主要能力与概念:
- Service 与 Method:服务是一组相关端点的命名集合(如 remoteMcp、access、auditlogs),方法即单个端点。
- Payload/Result:方法的输入输出类型,由共享安全 payload 与特定表单属性组合。
- 安全机制:管理端点使用 Session(浏览器 cookie)、ByKey(API key 头)和 ProjectSlug(项目选择头)三种方案。
- Model views(mv):将数据库行类型转换为 API 响应类型的无状态函数,处理器只返回视图,不直接返回仓库类型。
- 管理 API 与公共 SDK:同一 Goa 设计生成内部与公共两份 OpenAPI,公共规格由内部规格经脱敏 overlay 派生,仅内部 SDK 可访问全部端点。
- Changeset:随变更写入的短日志文件,标明 server、dashboard、sdk 等包的版本升级类型(patch、minor、major)。
使用方式:新增方法需编辑 server/design/<svc>/design.go 添加 Method 块,运行 mise run gen:goa-server;实现 server/internal/<svc>/impl.go 中的处理器;按需添加 SQLc 查询并运行 mise run gen:sqlc-server;添加视图构建器、RBAC 作用域与审计事件;编写测试;最后运行 mise run gen:sdk 同步 SDK 与 OpenAPI,并添加 changeset。新增服务还需在 server/design/gram.go 中空白导入、配置 sqlc.yaml、添加 URN 类型并在 start.go 中挂载。重命名端点或覆盖 SDK/hook 名称应修改 OpenAPI 元数据(operationId、x-speakeasy-name-override、x-speakeasy-react-hook)而非 Go 符号。设计变更后需按顺序重新生成。
适用场景:为 Gram 平台添加或修改管理端点、调整 payload/result 类型、统一 SDK 与 CLI 契约,以及需要版本化内部接口的开发者。
限制:HTTP 路径由 Goa 服务与方法名派生,重命名是破坏性变更;新增必填字段和删除属性不向后兼容;关于收费、部署平台或具体效果资料暂未提供。