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