80 lines
4.0 KiB
Markdown
80 lines
4.0 KiB
Markdown
# API 驱动的用户管理示例
|
||
|
||
这个独立 Go module 从 `api/user.api` 生成，随后在开发者拥有的文件中实现业务。
|
||
使用 MySQL 持久化、事务审计、环境变量 Token 鉴权、文件日志和 local 存储；业务层只接收标准 context 和基础模块接口。
|
||
|
||
## 启动
|
||
|
||
先准备空的业务数据库，再设置环境变量（替换占位值，密钥不写进配置或 Git）：
|
||
|
||
```sh
|
||
export GO_OMNI_DB_DSN='user:password@tcp(127.0.0.1:3306)/user_service?parseTime=true'
|
||
export USER_SERVICE_API_TOKEN='<至少32字节的随机值>'
|
||
export GO_OMNI_STORAGE_SIGNING_KEY='<另一个至少32字节的随机值>'
|
||
export GO_OMNI_STORAGE_PUBLIC_URL='http://127.0.0.1:8080/storage/object'
|
||
go mod tidy
|
||
# 在本目录运行与框架版本一致的 CLI；迁移必须显式执行。
|
||
go-omni migrate --dir migrations --apply
|
||
go run ./cmd/server
|
||
```
|
||
|
||
源码示例的 go.mod 使用 `replace ... => ../..`。复制到独立仓库时，删除这条 replace，
|
||
保留已发布的固定依赖版本，再执行 go mod tidy。远程版本验证脚本会自动检查没有本地替换。
|
||
`GO_OMNI_TRANSPORT=native` 可切换为 native，业务代码无需调整。
|
||
|
||
配置是默认值 → etc/config.yaml → 环境变量。日志默认写入 var/log/server.log 并轮转，
|
||
`GO_OMNI_LOG_OUTPUT=stderr` 可以切换为标准错误输出。MySQL 默认最多 10 条连接。
|
||
应用检查 users 和 user_audit 表，缺失时拒绝启动，不自动改表。
|
||
|
||
## 接口
|
||
|
||
除健康检查、OpenAPI 和持有效签名的对象下载外，业务接口需要 `Authorization: Bearer <Token>`。
|
||
这个 Token 代表示例的管理员；可通过同一个命名中间件槽位替换为 JWT/OIDC 和业务授权策略。
|
||
框架不会推断租户模型或自动给接口放行。
|
||
|
||
| 接口 | 行为 |
|
||
| --- | --- |
|
||
| POST /api/v1/users | 创建，返回 201；邮箱规范化并唯一 |
|
||
| GET /api/v1/users/:id | 查询，缺失返回 404 |
|
||
| GET /api/v1/users?page=1&pageSize=20 | 分页，pageSize 最大 100，空结果返回 [] |
|
||
| PUT /api/v1/users/:id | 完整更新；邮箱冲突返回 409 |
|
||
| DELETE /api/v1/users/:id | 删除，返回 204 |
|
||
| POST /api/v1/users/:id/export | 私有文本导出，返回 5 分钟下载链接 |
|
||
| GET /health/ready | 数据库不可用时返回 503，恢复后重新就绪 |
|
||
| GET /openapi.json | 与 docs/openapi.json 一致 |
|
||
|
||
参数不合法返回 400，认证失败 401，邮箱重复 409，内部故障只返回通用 500。
|
||
OpenAPI 的业务数据类型来自契约；401/404/409 的业务错误码见上表。
|
||
|
||
创建、更新、删除都会在**同一个 MySQL 事务**写入 user_audit；审计写入失败时业务变更一起回滚。
|
||
事务提交后才写成功业务日志，requestId 同时出现在 HTTP 响应、业务日志和审计记录。
|
||
数据库异常日志不记录 SQL、DSN 或用户输入。
|
||
|
||
文件导出演示 `deps.Uploads` 和 `deps.Downloads`。对象使用随机 key，签名 URL 不进入日志。
|
||
签名过期只限制下载，不删除文件；实际项目应给 exports/ 配置保留期限或清理任务。
|
||
只签发下载链接，不对外开放任意对象上传或签名接口。
|
||
|
||
## 开发与验证
|
||
|
||
```sh
|
||
go-omni api generate --api api/user.api --dir .
|
||
go-omni api generate --api api/user.api --dir . --check
|
||
go test ./...
|
||
```
|
||
|
||
Gen.go 和 docs/openapi.json 由生成器维护；Service、Repository、迁移、鉴权、配置和 main 保留。
|
||
修改 .api 的类型/方法签名后，需要同步修改自己的业务实现并运行测试。
|
||
|
||
在框架仓库运行：
|
||
|
||
```sh
|
||
python3 scripts/verifyAPIWorkflow.py
|
||
# 已发布版本：全新 module cache 安装 CLI，无本地 replace 消费框架。
|
||
python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview \
|
||
--report performance/apiWorkflowRemote.json
|
||
```
|
||
|
||
验收创建只绑定 localhost 的临时 MySQL 容器（1 CPU / 768 MiB），使用随机密钥，结束时删除。
|
||
覆盖 nethttp/native 的 CRUD、校验、鉴权、事务错误/异常/取消回滚、数据库停机恢复、
|
||
重启持久化、签名文件下载、文件日志与优雅退出。不会连接业务服务器。
|