111 lines
4.5 KiB
Cheetah
111 lines
4.5 KiB
Cheetah
# GoOmni service
|
||
|
||
This service was generated with `go-omni new`.
|
||
{{if .Modules}}
|
||
**本项目启用了模块化配置，启动步骤和环境变量请先看 [MODULES.md](MODULES.md)。** 配置来自 `etc/config.yaml`，文件模块需要配置环境密钥后启动。
|
||
{{end}}
|
||
|
||
Framework dependency: `git.yuntuo.hk/k2safe/go-omni {{.FrameworkVersion}}`.
|
||
|
||
Database: `{{.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
|
||
```
|
||
|
||
配置入口是 `internal/settings.Config`、`Default()`、`Validate()` 和 `etc/config.yaml`。
|
||
只有文件里的 `${NAME}` / `${NAME:-fallback}` 会读取环境变量，固定值不受进程环境覆盖。生成的文件已声明地址、网络层，以及所选数据库/存储的必要引用；其他参数直接写进文件。
|
||
|
||
```yaml
|
||
server:
|
||
address: "${GO_OMNI_HTTP_ADDR:-127.0.0.1:8080}"
|
||
transport: "${GO_OMNI_TRANSPORT:-nethttp}"
|
||
log:
|
||
level: debug
|
||
shutdownTimeout: 10s
|
||
```
|
||
|
||
用 `-config` 选择一个 YAML/JSON/XML 文件；`-config ''` 只使用 Default()；`-check-config` 仅加载和校验，不创建依赖或监听：
|
||
|
||
```sh
|
||
go run ./cmd/server -config etc/config.yaml -check-config
|
||
go build -o server ./cmd/server
|
||
./server -config etc/config.yaml
|
||
```
|
||
|
||
服务通过 `signal.NotifyContext` 处理 `SIGINT` / `SIGTERM`，先排空 HTTP 请求，再关闭依赖和日志。生成项目默认提供 `/health/live` 和 `/health/ready`，业务依赖集中在 `internal/servicecontext`。
|
||
|
||
通过文件中的引用设置 `GO_OMNI_TRANSPORT=native` 可切换自研 HTTP/1.1，默认 nethttp。HTTPS 在文件的 `server.tls.certFile` / `server.tls.keyFile` 成对配置；实验 HTTP/2 选择 `http2` 且必须配置 TLS。不会自动读取未在文件声明的 TLS 环境变量。
|
||
{{if eq .Database "mysql"}}
|
||
`/health/ready` 已注册数据库探针，连接失败返回 503，恢复后返回 200；`/health/live` 只检查进程存活。连接池参数直接写入 `database`，缺失字段保留 Default()：
|
||
|
||
```yaml
|
||
database:
|
||
driver: mysql
|
||
dsn: "${GO_OMNI_DB_DSN}"
|
||
maxOpenConns: 10
|
||
maxIdleConns: 5
|
||
connMaxLifetime: 30m
|
||
connMaxIdleTime: 5m
|
||
pingTimeout: 5s
|
||
```
|
||
|
||
`maxIdleConns: 0` 禁用空闲连接；此项目要求 maxOpenConns 为正数。项目启用 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`。
|