# 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`。
