cli

gRPC Kit

主要基于以下几个核心类库实现：

• grpc
• grpc-gateway

简要概述

快速生成微服务模版，为同一产品提供统一的治理方式，提高多人协作效率

迁移已有项目

project migrate 用于把旧项目中由 grpc-kit-cli 管理的文件迁移到 pkg v0.5.0 兼容版本。默认只预览计划和 diff，不写文件：

grpc-kit-cli project migrate ./service

确认项目位于 clean Git 工作树、diff 符合预期，并完成输出中的人工迁移项后，可使用正式稳定版 CLI 应用托管文件变更：

grpc-kit-cli project migrate ./service --apply

命令只会更新首行带有完整 Code generated by "grpc-kit-cli/...". DO NOT EDIT. 标记、且存在内嵌兼容资产的已有文件；scripts/generate.sh 的标记位于第二行（首行是 shebang），0.5.1 之前的存量副本没有标记，迁移凭"路径精确 + 全文 SHA-256 匹配冻结历史版本"的内容证据整文件同步到最新服务模板并补上标记，本地修改过或内容不明的副本只会得到 generate_script_modified 人工核对提示而不被覆盖，文件缺失则不创建。命令不会修改 go.mod、业务源码或其他用户管理文件，也不会创建、删除或重命名文件。Manual action 表示仍需完成的 Go 版本、pkg、logrus/slog 或 context API 迁移，因此“托管文件已迁移”不等于“项目已通过编译验证”。根级 upgrade/update 不用于项目迁移；未来 CLI 自身更新保留 self update 语义。

旧服务的用户源码可使用 grpc-kit 共享技能 migrate-logrus-to-slog 进行 AI 辅助迁移；安装共享技能后入口为 scripts/skills/skills/migrate-logrus-to-slog/SKILL.md。该技能可以在用户明确授权后修改业务源码和依赖，但不会放宽 project migrate 的 marker 写入规则，迁移结果仍需经过 diff 审阅、生成、测试和构建。

生成代码并运行（本机方式）

创建应用模版

mkdir -p $GOPATH/src/github.com/opsaid
cd $GOPATH/src/github.com/opsaid

grpc-kit-cli new -t service -p opsaid -s test1

# 可选：指定输出目录；目标路径已存在时命令会拒绝覆盖
grpc-kit-cli new -t service -p opsaid -s test1 --output ./services/test1

new 会先在同级临时目录完成全部渲染，再一次性发布目标目录。渲染或写入失败不会留下半生成项目。

下载依赖的环境

make protoc
make protoc-gen-go
make protoc-gen-go-grpc
make protoc-gen-grpc-gateway
make protoc-gen-openapiv2

运行应用代码

make run

生成代码并运行（容器方式）

创建应用模版

docker run \
    --rm \
    -v $(pwd):/usr/local/src \
    -w /usr/local/src \
    ccr.ccs.tencentyun.com/grpc-kit/cli:0.5.0 \
    grpc-kit-cli new -t service -p opsaid -s test1

运行应用代码

docker run -i -t --rm \
    -v $GOPATH/pkg:/go/pkg \
    -v $(pwd):/usr/local/src \
    -w /usr/local/src \
    --network host \
    ccr.ccs.tencentyun.com/grpc-kit/cli:0.5.0 \
    make run

服务访问测试

• 微服务接口文档

http://127.0.0.1:8080/openapi-spec/

• 微服务编译版本

# curl http://127.0.0.1:8080/version | python -m json.tool

{
    "appname": "test1.v1.opsaid",
    "build_date": "2023-01-13T09:10:45Z",
    "git_commit": "1234567890123456789012345678901234567890",
    "git_branch": "",
    "go_version": "go1.18.5",
    "compiler": "gc",
    "platform": "darwin/amd64",
    "cli_version": "0.2.3",
    "commit_unix_time": 0,
    "release_version": "0.1.0"
}

• 微服务性能数据

# curl http://127.0.0.1:8080/metrics

# HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles.
# TYPE go_gc_duration_seconds summary
go_gc_duration_seconds{quantile="0"} 0.000114581
go_gc_duration_seconds{quantile="0.25"} 0.000873528
go_gc_duration_seconds{quantile="0.5"} 0.002296699
go_gc_duration_seconds{quantile="0.75"} 0.003722618
go_gc_duration_seconds{quantile="1"} 0.010592338
go_gc_duration_seconds_sum 0.033207328
go_gc_duration_seconds_count 12
# HELP go_goroutines Number of goroutines that currently exist.
# TYPE go_goroutines gauge
go_goroutines 19

...

• 微服务健康探测

探测流量仅到 gateway 不会调度到 grpc 服务。

# curl http://127.0.0.1:8080/ping
OK

探测流量同时到 gateway 与 grpc 服务。

# curl 'http://127.0.0.1:8080/api/healthz?service=test1.v1.opsaid'
{"status":"SERVING"}

• 示例 demo 接口

# curl -u user1:grpc-kit-cli http://127.0.0.1:8080/api/demo

发布与兼容验证

# CLI 全量单测与 vet
make test

# 冻结迁移资产对最低支持 pkg 的兼容验证
make test-compatibility PKG_COMPAT_VERSION=v0.5.0

# 最新 new 模板的生成、代码生成、单测与构建验证
make test-template-compatibility

test-compatibility 验证历史迁移资产，不会因以后发布 pkg v0.5.8 而失效。发布同一兼容系列的新补丁时，应保留 v0.5.0 最低基线，并额外对候选版本执行一次；只有引入新的破坏性目标时才新增迁移资产族。

脚本需要稳定消费 CLI 版本号时可使用：

grpc-kit-cli version --short