Files

lanyuanxiaoyao f18904af1e feat: 实现分层架构，包含 domain、service、repository 和 pkg 层

- 新增 domain 层：model、provider、route、stats 实体
- 新增 service 层：models、providers、routing、stats 业务逻辑
- 新增 repository 层：models、providers、stats 数据访问
- 新增 pkg 工具包：errors、logger、validator
- 新增中间件：CORS、logging、recovery、request ID
- 新增数据库迁移：初始 schema 和索引
- 新增单元测试和集成测试
- 新增规范文档：config-management、database-migration、error-handling、layered-architecture、middleware-system、request-validation、structured-logging、test-coverage
- 移除 config 子包和 model_router（已迁移至分层架构）

2026-04-16 00:47:20 +08:00

6.8 KiB

Raw Blame History

AI Gateway Backend

AI 网关后端服务，提供统一的大模型 API 代理接口。

功能特性

支持 OpenAI 协议（/v1/chat/completions）
支持 Anthropic 协议（/v1/messages）
支持流式响应（SSE）
支持 Function Calling / Tools
多供应商配置和路由
用量统计
结构化日志（zap + lumberjack）
YAML 配置管理
请求验证
中间件支持（请求 ID、日志、恢复、CORS）

技术栈

语言: Go 1.26+
HTTP 框架: Gin
ORM: GORM
数据库: SQLite
日志: zap + lumberjack
配置: gopkg.in/yaml.v3
验证: go-playground/validator/v10
迁移: goose

项目结构

backend/
├── cmd/
│   └── server/
│       └── main.go              # 主程序入口（依赖注入）
├── internal/
│   ├── config/                  # 配置管理
│   │   ├── config.go            # 配置加载/保存/验证
│   │   └── models.go            # GORM 数据模型
│   ├── domain/                  # 领域模型
│   │   ├── provider.go
│   │   ├── model.go
│   │   ├── stats.go
│   │   └── route.go
│   ├── handler/                 # HTTP 处理器
│   │   ├── middleware/          # 中间件
│   │   │   ├── request_id.go
│   │   │   ├── logging.go
│   │   │   ├── recovery.go
│   │   │   └── cors.go
│   │   ├── openai_handler.go
│   │   ├── anthropic_handler.go
│   │   ├── provider_handler.go
│   │   ├── model_handler.go
│   │   └── stats_handler.go
│   ├── protocol/                # 协议适配器
│   │   ├── openai/
│   │   │   ├── types.go         # 请求/响应类型 + 验证
│   │   │   └── adapter.go       # OpenAI 协议适配
│   │   └── anthropic/
│   │       ├── types.go         # 请求/响应类型 + 验证
│   │       ├── converter.go     # 协议转换
│   │       └── stream_converter.go  # 流式转换
│   ├── provider/                # 供应商客户端
│   │   └── client.go
│   ├── repository/              # 数据访问层
│   │   ├── provider_repo.go     # 接口定义
│   │   ├── provider_repo_impl.go
│   │   ├── model_repo.go
│   │   ├── model_repo_impl.go
│   │   ├── stats_repo.go
│   │   └── stats_repo_impl.go
│   └── service/                 # 业务逻辑层
│       ├── provider_service.go       # 接口定义
│       ├── provider_service_impl.go
│       ├── model_service.go
│       ├── model_service_impl.go
│       ├── routing_service.go
│       ├── routing_service_impl.go
│       ├── stats_service.go
│       └── stats_service_impl.go
├── pkg/                         # 公共包
│   ├── errors/                  # 结构化错误
│   │   ├── errors.go
│   │   └── wrap.go
│   ├── logger/                  # 日志系统
│   │   ├── logger.go
│   │   ├── rotate.go
│   │   └── context.go
│   └── validator/               # 验证器
│       └── validator.go
├── migrations/                  # 数据库迁移
│   ├── 001_initial_schema.sql
│   └── 002_add_indexes.sql
├── tests/                       # 测试
│   ├── helpers.go
│   ├── integration/
│   ├── unit/
│   └── testdata/
├── Makefile
├── go.mod
└── README.md

架构

采用三层架构（handler → service → repository），通过依赖注入连接：

handler（HTTP 请求处理）
  → service（业务逻辑）
    → repository（数据访问）

运行方式

安装依赖

go mod download

启动服务

go run cmd/server/main.go

服务将在端口 9826 启动。首次启动会自动创建配置文件和运行数据库迁移。

配置

配置文件位于 ~/.nex/config.yaml，首次启动自动生成。

server:
  port: 9826
  read_timeout: 30s
  write_timeout: 30s

database:
  path: ~/.nex/config.db
  max_idle_conns: 10
  max_open_conns: 100
  conn_max_lifetime: 1h

log:
  level: info
  path: ~/.nex/log
  max_size: 100        # MB
  max_backups: 10
  max_age: 30          # 天
  compress: true

数据文件：

~/.nex/config.yaml - 配置文件
~/.nex/config.db - SQLite 数据库
~/.nex/log/ - 日志目录

测试

# 运行所有测试
make test

# 生成覆盖率报告
make test-coverage

数据库迁移

# 使用 Makefile
make migrate-up DB_PATH=~/.nex/config.db
make migrate-down DB_PATH=~/.nex/config.db
make migrate-status DB_PATH=~/.nex/config.db

# 或直接使用 goose
goose -dir migrations sqlite3 ~/.nex/config.db up

API 文档

代理接口

OpenAI Chat Completions

POST /v1/chat/completions

请求示例：

{
  "model": "gpt-4",
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "stream": false
}

Anthropic Messages

POST /v1/messages

请求示例：

{
  "model": "claude-3-opus",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": [{"type": "text", "text": "Hello"}]}
  ]
}

管理接口

供应商管理

GET /api/providers - 列出所有供应商
POST /api/providers - 创建供应商
GET /api/providers/:id - 获取供应商
PUT /api/providers/:id - 更新供应商
DELETE /api/providers/:id - 删除供应商

创建供应商示例：

{
  "id": "openai",
  "name": "OpenAI",
  "api_key": "sk-...",
  "base_url": "https://api.openai.com/v1"
}

重要说明：

base_url 应配置到 API 版本路径，不包含具体端点
OpenAI: https://api.openai.com/v1
GLM: https://open.bigmodel.cn/api/paas/v4
其他 OpenAI 兼容供应商根据其文档配置版本路径

模型管理

GET /api/models - 列出模型（支持 ?provider_id=xxx 过滤）
POST /api/models - 创建模型
GET /api/models/:id - 获取模型
PUT /api/models/:id - 更新模型
DELETE /api/models/:id - 删除模型

创建模型示例：

{
  "id": "gpt-4",
  "provider_id": "openai",
  "model_name": "gpt-4"
}

统计查询

GET /api/stats - 查询统计
GET /api/stats/aggregate - 聚合统计

查询参数：

provider_id - 供应商 ID
model_name - 模型名称
start_date - 开始日期（YYYY-MM-DD）
end_date - 结束日期（YYYY-MM-DD）
group_by - 聚合维度（provider/model/date）

开发

构建

make build

代码检查

make lint

环境要求

Go 1.26 或更高版本

6.8 KiB Raw Blame History Unescape Escape