框架架构
1分钟内可阅读完
三个仓库的关系
| 仓库 | 输入 | 输出 | 使用方 |
|---|---|---|---|
| api | Proto、Gateway/OpenAPI YAML | 公共协议及生成配置 | pkg 生成流程、应用代码生成 |
| pkg | 公共协议、运行时配置 | Go 运行时及 pkg/api 生成代码 | CLI 生成的应用 |
| cli | 模板和用户参数 | 应用源码、生成脚本、测试与部署模板 | 业务开发者 |
API 与 pkg 生成文件必须同步评审；CLI 模板又固定 pkg 依赖。它们有独立版本，参见版本与兼容。
一个进程内的装配
当前模板以 handler.Microservice 作为业务服务入口，持有 RPC Server/Client、日志、框架 LocalConfig 和业务 IndependentCfg。业务 RPC 与可选 KnownAdmin 服务注册到同一 gRPC Server，HTTP Gateway 通过本机 gRPC endpoint 调用它们。
这支持微单体的部署方式。领域边界、依赖方向和数据归属仍需由业务项目组织；当前模板没有提供领域模块清单、依赖拓扑排序或逐模块生命周期管理器。不要把“同进程部署”理解为已有完整模块框架。
启动顺序
LocalConfig.Init初始化配置及基础依赖。privateExtended装配业务依赖，IndependentCfg.Init初始化业务资源。- 注册业务 RPC、gRPC health 和框架/Admin Gateway。
- 加载安全策略，注册前端并同步完成 MCP AutoBridge。
- 调用
privateHTTPHandle、privateMCPHandle，挂载 HTTP Gateway。 StartBackground启动 gRPC 与 HTTP 监听。
请求路径
| 入口 | 路径 | 需要注意 |
|---|---|---|
| gRPC | 客户端 → gRPC interceptor → 业务 handler | deadline、认证及权限策略 |
| HTTP API | HTTP → Gateway → 本机 gRPC → handler | 经过 JSON/Proto 转换与本机 RPC |
| MCP AutoBridge | MCP → 本机 HTTP Gateway → gRPC → handler | 复用业务路径，也增加转换与调用开销 |
| 原生 MCP | MCP → 自定义 Tool/Resource/Prompt | 业务授权和审计由实现负责 |
不能将上述入口视为同等延迟，也不能假设原生 MCP 自动执行 RPC 的 OPA 策略。公开接口前按代码边界和MCP 实践核对。
当前运行边界
初始化尚无全局事务回滚；资源释放、健康检查与关闭超时需应用补足。Prometheus 注册及 OpenTelemetry provider 涉及进程全局状态，同进程创建多个独立服务实例需专项验证。模块独立扩容、故障隔离或单独交付成为明确需求时，可以保持契约并拆出进程，但需要重新设计网络调用、数据一致性和部署治理。