重构项目的实现,优化使用方法与使用逻辑
This commit is contained in:
429
INTEGRATION.md
Normal file
429
INTEGRATION.md
Normal file
@@ -0,0 +1,429 @@
|
||||
# GoCommon 业务项目对接操作手册
|
||||
|
||||
本文档供**引用 GoCommon 的业务项目**使用。按本手册对接即可，无需重复沟通基础设施实现方式。
|
||||
|
||||
模块路径：`git.toowon.com/jimmy/go-common`
|
||||
|
||||
> 本文档只描述**目标架构**，重构时一步到位，**不提供过渡期用法，不考虑向后兼容**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 对接原则
|
||||
|
||||
| 原则 | 说明 |
|
||||
|------|------|
|
||||
| Factory 只是入口 | 启动时初始化一次，通过 getter 获取各模块**对象** |
|
||||
| 能力在模块自身 | 使用 `log.Info()`、`db.Find()`、`store.Upload()`，不在 Factory 上堆透传方法 |
|
||||
| 按需引用 | 用什么模块取什么对象；无状态工具直接 `import tools` |
|
||||
| 不重写基础设施 | 数据库连接、Redis 客户端、统一 HTTP 出参、中间件链由 GoCommon 提供 |
|
||||
| 业务只管业务 | Service 返回数据；Handler 交给 `http.Handler` 出参；Migration 只写 SQL 文件 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 环境准备
|
||||
|
||||
### 2.1 配置私有模块
|
||||
|
||||
```bash
|
||||
go env -w GOPRIVATE=git.toowon.com
|
||||
go env -w GONOPROXY=git.toowon.com
|
||||
go env -w GONOSUMDB=git.toowon.com
|
||||
```
|
||||
|
||||
### 2.2 Git 认证（SSH 推荐）
|
||||
|
||||
```bash
|
||||
git config --global url."git@git.toowon.com:".insteadOf "https://git.toowon.com/"
|
||||
```
|
||||
|
||||
### 2.3 安装依赖
|
||||
|
||||
```bash
|
||||
go get git.toowon.com/jimmy/go-common@v2.0.0
|
||||
```
|
||||
|
||||
在 `go.mod` 中：
|
||||
|
||||
```go
|
||||
require git.toowon.com/jimmy/go-common v2.0.0
|
||||
```
|
||||
|
||||
配置示例见 [`config/example.json`](./config/example.json)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 推荐项目结构
|
||||
|
||||
```text
|
||||
your-project/
|
||||
├── config.json
|
||||
├── cmd/
|
||||
│ ├── server/main.go
|
||||
│ └── migrate/main.go # 从 templates/migrate/main.go 复制
|
||||
├── migrations/
|
||||
│ └── 20240101000001_create_users.sql
|
||||
├── locales/ # i18n（可选）
|
||||
│ ├── zh-CN.json
|
||||
│ └── en-US.json
|
||||
├── internal/
|
||||
│ ├── handler/
|
||||
│ └── service/
|
||||
└── go.mod
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 启动初始化（只做一次）
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
"net/http"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/factory"
|
||||
)
|
||||
|
||||
func main() {
|
||||
if err := factory.Init("config.json"); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
app := factory.Default()
|
||||
chain := app.MiddlewareChain()
|
||||
chain.Append(yourAuthMiddleware)
|
||||
|
||||
userSvc, err := NewUserService(app)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
http.Handle("/api/users", chain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
listUsers(w, r, userSvc, app)
|
||||
}))
|
||||
log.Fatal(http.ListenAndServe(":8080", nil))
|
||||
}
|
||||
```
|
||||
|
||||
**禁止**在每个 Handler 里 `NewFromFile` / `Init`。全局只初始化一次，通过 `factory.Default()` 或注入 `*factory.Factory`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 获取模块对象（Factory getter）
|
||||
|
||||
连接与客户端由 Factory **lazy 初始化并缓存**。业务侧**不要**自行 `gorm.Open` / `redis.NewClient`。
|
||||
|
||||
| 模块 | API | 用法 |
|
||||
|------|-----|------|
|
||||
| 配置 | `app.Config()` | 读原始配置 |
|
||||
| 数据库 | `app.Database()` | `db.Find(&users)`、`db.Transaction(...)` |
|
||||
| Redis | `app.Redis()` | `rds.Set(ctx, key, val, ttl)` |
|
||||
| 日志 | `app.Logger()` | `log.Info(...)`，退出前 `log.Close()` |
|
||||
| 存储 | `app.Storage()` | `store.Upload(ctx, key, reader)` |
|
||||
| 邮件 | `app.Email()` | `mail.SendEmail(...)` |
|
||||
| 短信 | `app.SMS()` | `sms.SendSMS(...)` |
|
||||
| Excel | `app.Excel()` | `ex.ExportToFile(...)` |
|
||||
| 国际化 | `app.I18n()` | 供 `http.Handler` 注入；或 `i18n.GetMessage(...)` |
|
||||
| 中间件链 | `app.MiddlewareChain()` | `chain.Append(...).ThenFunc(...)` |
|
||||
| 迁移 | `app.Migrator("migrations")` | `m.Up()` / `m.Status()` / `m.Down()` |
|
||||
|
||||
### 注入 Service 示例
|
||||
|
||||
```go
|
||||
type UserService struct {
|
||||
db *gorm.DB
|
||||
rds *redis.Client
|
||||
}
|
||||
|
||||
func NewUserService(app *factory.Factory) (*UserService, error) {
|
||||
db, err := app.Database()
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
rds, err := app.Redis()
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &UserService{db: db, rds: rds}, nil
|
||||
}
|
||||
|
||||
func (s *UserService) List(page, size int) (users []User, total int64, err error) {
|
||||
s.db.Model(&User{}).Count(&total)
|
||||
err = s.db.Offset((page-1)*size).Limit(size).Find(&users).Error
|
||||
return
|
||||
}
|
||||
```
|
||||
|
||||
`config.json` 未配置的模块，调用 getter 会返回错误——**只配置使用的模块即可**。
|
||||
|
||||
---
|
||||
|
||||
## 6. HTTP 统一出参
|
||||
|
||||
### 6.1 职责划分
|
||||
|
||||
| 层级 | 做什么 |
|
||||
|------|--------|
|
||||
| Service | 返回 `[]User`、`total`、业务 error |
|
||||
| Handler | 解析请求、调 Service、通过 `http.Handler` 出参 |
|
||||
| `http.Handler` | PageData → Response → JSON（结构 / 编码 / 语种 / 时间统一） |
|
||||
|
||||
**禁止**在 Service 拼 JSON，**禁止**在业务项目自定义 `Response` 结构，**禁止**经 Factory 出参（无 `app.Success` / `app.Error`）。
|
||||
|
||||
### 6.2 标准响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"timestamp": 1704067200,
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
分页时 `data`：
|
||||
|
||||
```json
|
||||
{
|
||||
"list": [],
|
||||
"total": 100,
|
||||
"page": 1,
|
||||
"pageSize": 20
|
||||
}
|
||||
```
|
||||
|
||||
类型定义在 `http` 包：`http.Response`、`http.PageData`。
|
||||
|
||||
### 6.3 Handler 用法（唯一方式）
|
||||
|
||||
中间件链须包含 `Language`、`Timezone`（`MiddlewareChain()` 已默认组装）。
|
||||
|
||||
```go
|
||||
import commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
|
||||
func listUsers(w http.ResponseWriter, r *http.Request, svc *UserService, app *factory.Factory) {
|
||||
i18n, _ := app.I18n()
|
||||
h := commonhttp.NewHandler(w, r, commonhttp.WithI18n(i18n))
|
||||
|
||||
var req ListUserRequest
|
||||
if err := h.ParseJSON(&req); err != nil {
|
||||
h.Error("common.invalid_request")
|
||||
return
|
||||
}
|
||||
|
||||
p := h.Pagination()
|
||||
users, total, err := svc.List(p.GetPage(), p.GetPageSize())
|
||||
if err != nil {
|
||||
h.Error("user.list_failed")
|
||||
return
|
||||
}
|
||||
|
||||
h.SuccessPage(users, total)
|
||||
}
|
||||
```
|
||||
|
||||
`http.Handler` 统一负责：
|
||||
|
||||
- `Content-Type: application/json; charset=utf-8`
|
||||
- 从 context 读取语种、时区
|
||||
- 消息码（如 `user.not_found`）经 i18n 转为文案与业务 code
|
||||
- `timestamp` 按统一时区策略写入
|
||||
|
||||
### 6.4 请求头约定
|
||||
|
||||
| Header | 用途 |
|
||||
|--------|------|
|
||||
| `Accept-Language` | 响应消息语种 |
|
||||
| `X-Timezone` | 时区（默认 `Asia/Shanghai`） |
|
||||
|
||||
---
|
||||
|
||||
## 7. 数据库迁移
|
||||
|
||||
执行框架已封装，业务**只写 SQL 文件**。
|
||||
|
||||
### 7.1 推荐：独立 migrate 命令（与 Web 解耦）
|
||||
|
||||
```bash
|
||||
cp templates/migrate/main.go cmd/migrate/main.go
|
||||
go build -o bin/migrate cmd/migrate/main.go
|
||||
|
||||
./bin/migrate up
|
||||
./bin/migrate status
|
||||
./bin/migrate down
|
||||
./bin/migrate up -config config.json -dir migrations
|
||||
```
|
||||
|
||||
```sql
|
||||
-- migrations/20240101000001_create_users.sql
|
||||
CREATE TABLE users (
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
username VARCHAR(255) NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
```sql
|
||||
-- migrations/20240101000001_create_users.down.sql
|
||||
DROP TABLE IF EXISTS users;
|
||||
```
|
||||
|
||||
独立 CLI 内部调用 `migration.RunMigrationsFromConfigWithCommand`，无需业务实现连接逻辑。
|
||||
|
||||
### 7.2 可选：经 Factory（开发 / 小项目）
|
||||
|
||||
```go
|
||||
m, err := app.Migrator("migrations")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
if err := m.Up(); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 Docker
|
||||
|
||||
```yaml
|
||||
command: sh -c "./bin/migrate up && ./bin/server"
|
||||
volumes:
|
||||
- ./config.json:/app/config.json:ro
|
||||
- ./migrations:/app/migrations:ro
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 各模块按需对接
|
||||
|
||||
### 8.1 日志
|
||||
|
||||
```go
|
||||
log, _ := app.Logger()
|
||||
defer log.Close()
|
||||
log.Info("服务启动")
|
||||
```
|
||||
|
||||
### 8.2 存储
|
||||
|
||||
```go
|
||||
store, _ := app.Storage()
|
||||
store.Upload(ctx, "images/a.jpg", fileReader, "image/jpeg")
|
||||
url, _ := store.GetURL("images/a.jpg", 3600)
|
||||
```
|
||||
|
||||
不经 Factory 时：`storage.NewStorage(storage.StorageTypeLocal, cfg)`。
|
||||
|
||||
### 8.3 邮件 / 短信
|
||||
|
||||
```go
|
||||
mail, _ := app.Email()
|
||||
defer mail.Close()
|
||||
|
||||
// HTTP 通知类：异步，不阻塞请求
|
||||
mail.SendEmailAsync(r.Context(), []string{"a@b.com"}, "主题", "正文")
|
||||
|
||||
// 验证码等需等待结果：同步
|
||||
mail.SendEmail([]string{"a@b.com"}, "主题", "正文")
|
||||
|
||||
sms, _ := app.SMS()
|
||||
defer sms.Close()
|
||||
sms.SendSMSAsync(r.Context(), []string{"13800138000"}, map[string]string{"code": "123456"})
|
||||
sms.SendSMS([]string{"13800138000"}, map[string]string{"code": "123456"})
|
||||
```
|
||||
|
||||
### 8.4 Excel
|
||||
|
||||
```go
|
||||
ex := app.Excel()
|
||||
ex.ExportToFile("users.xlsx", "用户列表", columns, users)
|
||||
```
|
||||
|
||||
### 8.5 国际化
|
||||
|
||||
```go
|
||||
i18n, _ := app.I18n()
|
||||
i18n.LoadFromDir("locales")
|
||||
msg := i18n.GetMessage("zh-CN", "user.not_found")
|
||||
```
|
||||
|
||||
HTTP 出参的 i18n 通过 `NewHandler(..., WithI18n(i18n))` 注入，Handler 内用消息码调用 `h.Error("user.not_found")`。
|
||||
|
||||
### 8.6 无状态工具（不经 Factory）
|
||||
|
||||
```go
|
||||
import "git.toowon.com/jimmy/go-common/tools"
|
||||
|
||||
tools.Now()
|
||||
tools.MD5("text")
|
||||
tools.YuanToCents(100.5)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. config.json 最小示例
|
||||
|
||||
```json
|
||||
{
|
||||
"database": {
|
||||
"type": "mysql",
|
||||
"host": "localhost",
|
||||
"port": 3306,
|
||||
"user": "root",
|
||||
"password": "password",
|
||||
"database": "mydb"
|
||||
},
|
||||
"logger": {
|
||||
"level": "info",
|
||||
"output": "both",
|
||||
"filePath": "./logs/app.log",
|
||||
"async": true
|
||||
},
|
||||
"i18n": {
|
||||
"defaultLang": "zh-CN",
|
||||
"localesDir": "locales"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
完整字段见 [`config/example.json`](./config/example.json)。
|
||||
|
||||
---
|
||||
|
||||
## 10. 反模式（禁止）
|
||||
|
||||
- 每个 Handler 内 `factory.Init` / `NewFromFile`
|
||||
- 业务 Service 内写 HTTP JSON 响应
|
||||
- 自行 `gorm.Open` / `redis.NewClient`
|
||||
- 使用 Factory 透传：`LogInfo`、`RedisSet`、`Success`、`Error`、`Now`、`MD5` 等
|
||||
- 直接调用 `http.Success(w, ...)` 包级函数（应使用 `http.Handler`）
|
||||
- 在业务项目复制 GoCommon 的 Response / 中间件实现
|
||||
|
||||
---
|
||||
|
||||
## 11. 故障排除
|
||||
|
||||
**无法下载模块：**
|
||||
|
||||
```bash
|
||||
go env -w GOPRIVATE=git.toowon.com
|
||||
git config --global url."git@git.toowon.com:".insteadOf "https://git.toowon.com/"
|
||||
go get git.toowon.com/jimmy/go-common@latest
|
||||
```
|
||||
|
||||
**依赖错误：** `go clean -modcache && go mod tidy`
|
||||
|
||||
**getter 报 config is nil：** 补充 `config.json` 对应段，或不调用该 getter
|
||||
|
||||
**迁移找不到文件：** 检查 `-dir` 与 SQL 文件命名
|
||||
|
||||
---
|
||||
|
||||
## 12. 文档与版本
|
||||
|
||||
| 文档 | 用途 |
|
||||
|------|------|
|
||||
| 本文档 | 业务项目对接 |
|
||||
| [README.md](./README.md) | 库概述 |
|
||||
| [VERSION.md](./VERSION.md) | 版本发布 |
|
||||
|
||||
版本升级见 [VERSION.md](./VERSION.md)。
|
||||
Reference in New Issue
Block a user