testbed.v1.known

grpc-kit 框架的测试床（testbed）——由 grpc-kit-cli（v0.5.1）脚手架生成的完整微服务工程， 服务于 grpc-kit 框架本身的测试目的。

项目定位

本仓库不承载业务，存在的唯一目的是测试 grpc-kit 框架：

• 发版验证：pkg 框架迭代后，在本工程中执行完整的生成、构建、单测、e2e 流程， 确认框架行为符合预期后再发版；
• 参考实现：脚手架能够生成的各层能力——API 契约与 HTTP 网关绑定、认证鉴权、 ent 数据模型、MCP 连接器、flow 编排等——都在这里保留最小可运行样例；
• 规范载体：test/e2e/ 的黑盒测试组织方式（按域分包、//go:build e2e、纯度约束） 以本工程为基准落地。

工程通过 go.mod 的 replace 始终跟踪同仓的本地框架代码，无需等待 pkg 发版：

replace github.com/grpc-kit/pkg => ../pkg

服务能力

gRPC 服务 KnownTestbed（服务代码 testbed.v1.known），并同时暴露 HTTP 网关：

RPC	HTTP	说明
HealthCheck	GET /api/healthz?service=<service_code>	健康检查，匿名可访问
Demo	POST /api/demo	创建示例资源，返回 pong 投影
Demo	GET /api/demo	列出示例资源，返回完整响应体
Demo	GET /api/demo/{uuid}	查询单个资源，返回 pong.pong 投影
Demo	PUT /api/demo/{uuid}	更新资源，返回 ping 投影
Demo	DELETE /api/demo/{uuid}	删除资源，返回 empty 投影

除健康检查（配置于 insecure_rpcs）外，HTTP 接口开启 Basic 认证； OpenAPI 文档由 scripts/generate.sh 生成并输出到 public/openapi/。

快速开始

前置条件

• 正确配置 GOPATH（make precheck 强制校验）；
• Go 1.25.13（版本以 go.mod 为准）；
• protoc 等工具链无需预装，make protoc / make protoc-gen-go 等目标会按需下载；
• config/app-dev-*.yaml 不入库（.gitignore），新环境需参考 config/app-mini.yaml 或 ../pkg/cfg/app-sample.yaml 重建 config/app-dev-local.yaml。

启动

make run

make run 会先执行代码生成（proto / ent），再以 config/app-dev-local.yaml 启动。默认监听：

协议	地址
gRPC	0.0.0.0:10081
HTTP 网关	0.0.0.0:8080

验证

# 健康检查（匿名）
curl 'http://127.0.0.1:8080/api/healthz?service=testbed.v1.known'

# 示例接口（Basic 认证，账号密码见 config/app-dev-local.yaml）
curl -u user1:grpc-kit-cli http://127.0.0.1:8080/api/demo

测试

make test        # 单测：代码生成 + go test ./...
make run         # 终端 1：本地起服务
make test-e2e    # 终端 2：黑盒 e2e（-tags=e2e，串行）

e2e 覆盖示例接口的全部 HTTP 绑定（用例 D1–D8），环境变量与常见故障排查见 test/e2e/README.md。

目录结构

api/known/testbed/v1/   # API 契约（*.proto）与生成的 RPC / 网关绑定
cmd/server/             # 服务启动入口（框架管理，勿手改）
handler/                # RPC 注册与服务处理器
modeler/                # 数据模型（ent）、flow 编排、MCP 资源注册
config/                 # 运行时配置（本地 / 最小环境）
scripts/                # 生成、环境检查、打包等自动化
test/e2e/               # 黑盒 API 端到端测试（//go:build e2e）
docs/                   # 模块设计文档
public/                 # 网关 OpenAPI 文档与前端静态产物
web/                    # 前端源代码（admin / webroot）

文件分为两类：首行带 // Code generated by "grpc-kit-cli/...". DO NOT EDIT. 的框架管理文件 （升级时会被覆盖）与业务可编辑文件，详见 AGENTS.md。

更多文档

• AGENTS.md — 工程约定（构建、测试、生成文件策略、提交规范）
• test/e2e/README.md — e2e 测试组织规范
• CHANGELOG.md — 变更记录
• docs/ — 模块设计文档