udeServer

udeServer

基于 go-zero 的 HTTP API 服务。项目由 goctl 生成，包含示例接口、数据库连通性检查，以及 t_directory、t_key、t_service 三张表的完整 CRUD 接口。

技术栈

组件	版本
Go	1.25.10
go-zero	v1.10.3
goctl	v1.10.2
MySQL	8.4.4（10.10.10.30:3306/ude）

目录结构

.
├── udeServer.api              # API 定义（接口的唯一事实来源）
├── udeserver.go               # 程序入口
├── etc/
│   └── udeserver-api.yaml     # 配置文件
├── internal/
│   ├── apierr/                # HTTP 状态码错误封装
│   ├── config/                # 配置结构体
│   ├── handler/               # HTTP handler 与路由注册
│   ├── logic/                 # 业务逻辑
│   ├── model/                 # goctl 生成的 model 与自定义查询
│   ├── svc/                   # ServiceContext，管理依赖
│   └── types/                 # 请求/响应类型
├── go.mod
└── go.sum

环境说明

• Go 1.25.10 安装在 C:\Users\Administrator\sdk\go1.25.10；系统默认的 go 仍为 1.24.0。
• 已设置 GOTOOLCHAIN=auto，因此在 go.mod 要求 go 1.25.10 时，Go 会自动切换到 1.25.10，无需手动修改 PATH。
• goctl 安装在 C:\Users\Administrator\go\bin\goctl.exe，该目录未加入 PATH，下文使用完整路径调用。
• 若希望命令行直接使用 1.25.10，可将 C:\Users\Administrator\sdk\go1.25.10\bin 放到 PATH 最前面。

快速开始

# 下载依赖（首次执行会按 go.mod 自动获取 Go 1.25.10 工具链）
go mod download

# 启动服务，默认监听 0.0.0.0:8880
go run udeserver.go -f etc/udeserver-api.yaml

# 另开终端验证
curl http://127.0.0.1:8880/api/v1/from/you
# {"message":"Hello you"}

curl http://127.0.0.1:8880/api/v1/db/ping
# {"ok":true,"version":"8.4.4","database":"ude"}

构建可执行文件：

go build -o bin/udeserver.exe udeserver.go
.\bin\udeserver.exe -f etc\udeserver-api.yaml

API 接口

三张表各有一组 CRUD 接口：

资源	新增	列表	详情	更新	删除
保护目录 t_directory	POST /directories	GET /directories	GET /directories/:id	PUT /directories/:id	DELETE /directories/:id
密钥 t_key	POST /keys	GET /keys	GET /keys/:id	PUT /keys/:id	DELETE /keys/:id
服务 t_service	POST /services	GET /services	GET /services/:id	PUT /services/:id	DELETE /services/:id

所有路由统一带 /api/v1 前缀，如 GET /api/v1/keys/:id。前缀在 udeServer.api 的 @server(prefix: /api/v1) 中配置，实际请求都需要加前缀；/from/:name 和 /db/ping 也不例外。

统一响应格式

所有接口（成功/失败）HTTP 状态恒为 200，返回 {code, message, data} 封装：

{
  "code": 100000,
  "message": "操作成功",
  "data": { "ok": true }
}

业务码：

code	含义
100000	操作成功
100001	参数错误（如缺少 name、id 非法）
100002	资源不存在
100003	服务器内部错误

• 失败响应：{"code":100xxx,"message":"错误描述","data":null}，前端只需判断 code。
• 全局封装在 udeserver.go 的 response.Register() 中注册，实现见 internal/response/。

分页

三个列表接口（目录/密钥/服务）统一支持分页，通过 query 参数传递：

• page：页码，默认 1
• pageSize：每页数量，默认 10，最大 100
• 响应 data：{"list":[...],"total":13}，total 为总条数；超出范围时 list 为 []

示例：GET /api/v1/keys?page=2&pageSize=5

服务接口示例：

# 新增服务：id 必填（t_service 主键没有 AUTO_INCREMENT）
curl -X POST http://127.0.0.1:8880/api/v1/services `
  -H "Content-Type: application/json" `
  -d "{\"id\":1,\"name\":\"demo\",\"ip\":\"10.0.0.1\",\"port\":\"8080\",\"iden\":\"svc-1\",\"keyIden\":\"key-1\",\"keyAlgo\":\"AES\",\"status\":\"active\"}"

# 列表 / 详情
curl http://127.0.0.1:8880/api/v1/services
curl http://127.0.0.1:8880/api/v1/services/1

# 更新：id 放在路径中，请求体为完整字段
curl -X PUT http://127.0.0.1:8880/api/v1/services/1 `
  -H "Content-Type: application/json" `
  -d "{\"name\":\"demo-updated\",\"ip\":\"10.0.0.2\",\"port\":\"9090\",\"iden\":\"svc-1\",\"keyIden\":\"key-1\",\"keyAlgo\":\"SM4\",\"status\":\"disabled\"}"

# 删除
curl -X DELETE http://127.0.0.1:8880/api/v1/services/1

密钥接口示例：

# 新增密钥：前端只需要传 name
curl -X POST http://127.0.0.1:8880/api/v1/keys `
  -H "Content-Type: application/json" `
  -d "{\"name\":\"demo-key\"}"

# 返回：id 自增，iden/content 服务端生成，status 默认 1，createAt 由数据库生成
# {"code":100000,"message":"操作成功","data":{"id":1,"iden":"4532bb4cefb944889d847020211ba7c7","name":"demo-key","content":"5e35...","status":"1","createAt":"2026-10-21T10:07:26+08:00"}}

说明：

• 密钥生成规则：iden 为去掉 - 的 UUIDv4；content 使用 PBKDF2-HMAC-SHA256（10 万次迭代、输出 32 字节、随机种子，iden 作盐）生成并转为十六进制；status 固定为 "1"；id、create_at 由数据库生成。
• PUT 为全量更新，未传的可选字段会写成 NULL（空字符串、serviceId=0 均按 NULL 处理）。
• 列表接口均已分页（见上），按 id 升序返回。
• 错误响应见「统一响应格式」一节，业务码 100001~100003。

修改接口

1. 编辑 udeServer.api（新增 type、service、路由）。
2. 重新生成代码：

C:\Users\Administrator\go\bin\goctl.exe api go -api udeServer.api -dir .

internal/logic 下的已有业务逻辑不会被覆盖，可放心迭代 API 定义。

配置

etc/udeserver-api.yaml：

Name: udeServer-api
Host: 0.0.0.0
Port: 8880

MySQL:
  DataSource: "ude:H3G8xzfYpAASYFxF@tcp(10.10.10.30:3306)/ude?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai"

说明：goctl 生成的默认端口是 8888，当前配置使用 8880。

数据库密码目前以明文写在配置中，请勿提交到公开仓库；生产环境建议使用环境变量或密钥管理服务注入。

go-zero 还支持在配置中开启日志、链路追踪、Prometheus 指标、限流等功能，按需在 rest.RestConf 基础上扩展 internal/config/config.go 即可。

数据库

• 连接地址：10.10.10.30:3306，数据库 ude，账号 ude
• 服务启动时通过 sqlx.MustNewConn(c.MySQL) 创建连接池（go-zero 默认 64 个连接，空闲回收 1 分钟）
• ServiceContext 中的 DB sqlx.SqlConn 可直接在 logic 层使用：

var count int64
err := l.svcCtx.DB.QueryRowCtx(l.ctx, &count, "SELECT COUNT(*) FROM your_table")

• 已为三张表生成 model（internal/model/）：TDirectoryModel、TKeyModel、TServiceModel，并在自定义 model 文件中补充了列表查询 FindAll。
• t_directory、t_service 的主键是普通 int，没有 AUTO_INCREMENT，新增时必须显式传 id；t_key.id 为自增主键，新增时不需要传。
• 新增表后可按表继续生成 model：

C:\Users\Administrator\go\bin\goctl.exe model mysql datasource ^
  -url "ude:H3G8xzfYpAASYFxF@tcp(10.10.10.30:3306)/ude" ^
  -table "your_table" -dir internal/model

后续扩展

• 接入 Redis：在 internal/config 中增加 Redis 配置，并在 internal/svc 中初始化客户端。
• 拆分 RPC 服务：goctl rpc new <service>，再在 ServiceContext 中注入 RPC 客户端。
• 多服务单仓库布局：将当前服务移动到 app/<service>/api 下，统一使用根 go.mod 管理。