110 lines
4.2 KiB
Cheetah
110 lines
4.2 KiB
Cheetah
# GoOmni service
|
||
|
||
This service was generated with `go-omni new`.
|
||
|
||
Framework dependency: `git.yuntuo.hk/k2safe/go-omni {{.FrameworkVersion}}`.
|
||
|
||
Storage: `{{.Database}}`.
|
||
|
||
{{if eq .Database "mysql"}}
|
||
先创建业务数据库，再执行项目的建表脚本（替换示例数据库名、账号和地址）：
|
||
|
||
```sh
|
||
mysql -h 127.0.0.1 -u app -p app < schema.sql
|
||
```
|
||
|
||
配置数据库连接后启动；初始化失败或缺少表结构时，服务会退出并关闭已创建的连接池：
|
||
|
||
```sh
|
||
export GO_OMNI_DB_DSN='app:password@tcp(127.0.0.1:3306)/app?parseTime=true'
|
||
```
|
||
|
||
应用只检查表结构，不会自动建库、建表或迁移。MySQL 驱动由本项目注册，核心框架仍依赖标准库 `database/sql`。
|
||
{{else}}
|
||
默认使用进程内存存储，服务重启后数据清空。需要 MySQL 时，生成新项目时选择 `--database mysql`。
|
||
{{end}}
|
||
|
||
```sh
|
||
go mod tidy
|
||
go run ./cmd/server
|
||
```
|
||
|
||
运行时配置从 `GO_OMNI_*` 环境变量加载，例如：
|
||
|
||
```sh
|
||
GO_OMNI_ENABLE_LOGGER=true GO_OMNI_LOG_LEVEL=debug go run ./cmd/server
|
||
```
|
||
|
||
`GO_OMNI_HTTP_ADDR` 可以修改监听地址。生成项目默认提供 `/health/live` 和
|
||
`/health/ready`，日志、请求 ID 和优雅退出等基础能力由 GoOmni 统一初始化；业务依赖集中放在项目自己的 `internal/servicecontext`。
|
||
|
||
服务使用 `signal.NotifyContext` 处理 `SIGINT` / `SIGTERM`。部署时构建并运行服务二进制，
|
||
使信号直接到达服务进程：
|
||
|
||
```sh
|
||
go build -o server ./cmd/server
|
||
./server
|
||
```
|
||
|
||
`GO_OMNI_SHUTDOWN_TIMEOUT` 控制等待请求完成的时间，默认 `10s`。
|
||
|
||
使用支持统一网络配置的框架版本时，设置 `GO_OMNI_TRANSPORT=native` 即可切换为自研 HTTP/1.1；
|
||
默认 `nethttp`。`GO_OMNI_TLS_CERT_FILE` 和 `GO_OMNI_TLS_KEY_FILE` 配对启用 HTTPS。
|
||
实验版 HTTP/2 使用 `GO_OMNI_TRANSPORT=http2`，必须同时配置 TLS 证书和私钥。
|
||
业务 Handler / Service / Repository 不需要修改；三种适配器共用上述退出等待时间。
|
||
{{if eq .Database "mysql"}}
|
||
`/health/ready` 已注册数据库探针：连接失败返回 `503`，数据库恢复后重新返回 `200`。
|
||
`/health/live` 始终只检查服务存活。`GO_OMNI_DB_PING_TIMEOUT` 限制初始化检查和数据库探针的等待时间。
|
||
退出时先排空 HTTP 请求，再关闭数据库连接池，最后关闭日志。
|
||
|
||
数据库连接池参数：
|
||
|
||
```text
|
||
GO_OMNI_DB_MAX_OPEN_CONNS=10
|
||
GO_OMNI_DB_MAX_IDLE_CONNS=5
|
||
GO_OMNI_DB_CONN_MAX_LIFETIME=30m
|
||
GO_OMNI_DB_CONN_MAX_IDLE_TIME=5m
|
||
GO_OMNI_DB_PING_TIMEOUT=5s
|
||
```
|
||
|
||
`MAX_IDLE_CONNS=0` 禁用空闲连接，`MAX_OPEN_CONNS=0` 表示不限制连接数。
|
||
项目会启用 MySQL `parseTime` 并按 UTC 读取 DATETIME 字段，JSON 字段保持 lowerCamelCase。
|
||
|
||
事务内复用 Repository（在业务代码中导入 `database/sql` 和项目的 `internal/repository`）：
|
||
|
||
```go
|
||
err := services.DB.InTx(ctx, nil, func(tx *sql.Tx) error {
|
||
users := repository.NewMySQLUsers(tx)
|
||
_, err := users.Create(ctx, input)
|
||
return err
|
||
})
|
||
```
|
||
|
||
业务函数返回错误、发生 panic 或 context 取消时会回滚。事务内必须使用基于 `tx` 创建的 Repository。
|
||
|
||
可选集成测试（只针对已应用 schema.sql 的独立测试数据库）：
|
||
|
||
```sh
|
||
GO_OMNI_TEST_MYSQL_DSN='app:password@tcp(127.0.0.1:3306)/test?parseTime=true' go test -race ./...
|
||
```
|
||
|
||
未设置 `GO_OMNI_TEST_MYSQL_DSN` 时跳过数据库集成测试。框架仓库中的 `scripts/verifyDatabase.py`
|
||
可以自动创建、验收和清理独立的 MySQL 容器。
|
||
{{else}}
|
||
内存模式没有外部依赖探针；后续添加依赖时，在 `internal/servicecontext` 注册检查与资源清理。
|
||
{{end}}
|
||
|
||
示例接口（无认证，接入实际业务时按项目需求添加认证中间件）：
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| POST | `/users` | 创建，JSON 包含 name、email |
|
||
| GET | `/users/:id` | 查询 |
|
||
| GET | `/users?page=1&pageSize=20` | 分页 |
|
||
| PUT | `/users/:id` | 更新 name、email |
|
||
| DELETE | `/users/:id` | 删除，返回 204 |
|
||
|
||
接口使用 GoOmni 统一响应，包含 code、message、data 和 requestId。邮箱按小写存储，重复返回 409；
|
||
无效输入返回 400，找不到记录返回 404。项目按 Handler / Service / Repository / Model 分层，
|
||
基础依赖集中放在 `internal/servicecontext`。
|