Claude Code Hub - Go 重写方案

一、项目概况

1.1 原项目分析

维度	现状 (Node.js)	说明
前端	Next.js 16 + React 19	管理后台 UI
后端	Hono 4	API 服务
数据库	PostgreSQL + Drizzle ORM	完整的表结构
缓存	Redis + ioredis	限流、会话缓存
代码量	~997 文件	包含前端

1.2 核心功能

代理网关: 转发 AI API 请求到多个供应商
多协议支持: Claude API、OpenAI 兼容 API、Codex API
用户管理: 用户、API Key、权限控制
供应商管理: 多供应商、权重分配、熔断器
配额限流: 多维度限流（RPM、日限额、周限额等）
会话管理: Session 跟踪、并发控制
费用统计: Token 计费、成本追踪
通知系统: Webhook 通知

二、技术栈选型

2.1 确定的技术栈

层级	选型	说明
Web 框架	Gin	高性能，HTTP/2 + SSE 支持
数据库	PostgreSQL	复用现有数据库
ORM	Bun + pgdriver	SQL-first，开发体验好
Redis	go-redis/v9	限流、缓存、会话
日志	zerolog	高性能结构化日志
配置	viper	环境变量 + 配置文件
验证	validator/v10	请求参数验证
HTTP 客户端	resty/v2	代理上游请求
金额计算	quagmt/udecimal	高性能、零分配精确金额计算
并发控制	golang.org/x/sync	errgroup 等

2.2 Go 模块依赖

// go.mod
module github.com/yourorg/claude-code-hub

go 1.23

require (
    // Web 框架
    github.com/gin-gonic/gin v1.10+

    // 数据库
    github.com/uptrace/bun v1.2+
    github.com/uptrace/bun/driver/pgdriver v1.2+
    github.com/uptrace/bun/dialect/pgdialect v1.2+

    // Redis
    github.com/redis/go-redis/v9 v9+

    // 配置 & 验证
    github.com/spf13/viper v1.19+
    github.com/go-playground/validator/v10 v10+

    // 日志
    github.com/rs/zerolog v1.33+

    // HTTP 客户端
    github.com/go-resty/resty/v2 v2.15+

    // 工具
    github.com/google/uuid v1.6+
    github.com/quagmt/udecimal v1.3+
    golang.org/x/sync v0.10+
)

2.3 前端策略

当前决定: 暂不考虑前端，先完成后端 API。

后续选项：

A. 保留 Next.js 前端，Go 只负责后端 API
B. 前端静态化，Go 服务内嵌静态文件
C. 使用 Vue/Svelte 重写轻量级前端

三、项目目录结构

claude-code-hub/
├── cmd/
│   └── server/
│       └── main.go                # 应用入口
│
├── internal/                      # 内部包
│   ├── config/                    # 配置管理
│   │   ├── config.go              # 配置结构体
│   │   └── loader.go              # viper 加载
│   │
│   ├── database/                  # 数据库连接
│   │   ├── postgres.go            # Bun 初始化
│   │   ├── redis.go               # go-redis 客户端
│   │   └── migrations/            # SQL 迁移文件
│   │
│   ├── model/                     # 数据模型 (对应 schema.ts)
│   │   ├── user.go
│   │   ├── key.go
│   │   ├── provider.go
│   │   ├── message_request.go
│   │   ├── model_price.go
│   │   └── ...
│   │
│   ├── repository/                # 数据访问层
│   │   ├── user_repo.go
│   │   ├── key_repo.go
│   │   ├── provider_repo.go
│   │   ├── statistics_repo.go
│   │   └── ...
│   │
│   ├── service/                   # 业务逻辑层
│   │   ├── auth/
│   │   │   └── auth.go            # API Key 认证
│   │   ├── ratelimit/
│   │   │   ├── service.go         # 多维度限流
│   │   │   ├── lua_scripts.go     # Redis Lua 脚本
│   │   │   └── time_utils.go
│   │   ├── circuitbreaker/
│   │   │   ├── breaker.go         # 熔断器状态机
│   │   │   └── state.go           # Redis 状态持久化
│   │   ├── session/
│   │   │   ├── manager.go         # Session 管理
│   │   │   └── tracker.go         # 并发追踪
│   │   ├── cost/
│   │   │   └── calculator.go      # Token 计费
│   │   ├── cache/
│   │   │   ├── provider_cache.go  # 供应商缓存
│   │   │   └── session_cache.go
│   │   └── notification/
│   │       ├── queue.go           # 通知队列
│   │       └── webhook.go         # Webhook 发送
│   │
│   ├── proxy/                     # 代理核心 (最重要)
│   │   ├── handler.go             # 代理主逻辑
│   │   ├── session.go             # ProxySession 上下文
│   │   ├── forwarder.go           # 上游请求转发
│   │   ├── sse.go                 # SSE 流处理
│   │   ├── provider_selector.go   # 供应商选择 (权重/优先级)
│   │   ├── guard/                 # Guard 链
│   │   │   ├── pipeline.go
│   │   │   ├── auth_guard.go
│   │   │   ├── ratelimit_guard.go
│   │   │   ├── provider_guard.go
│   │   │   └── ...
│   │   └── converter/             # 格式转换器
│   │       ├── claude.go
│   │       ├── openai.go
│   │       ├── gemini.go
│   │       └── codex.go
│   │
│   ├── handler/                   # HTTP 处理器
│   │   ├── v1/                    # 代理 API
│   │   │   ├── messages.go        # /v1/messages
│   │   │   ├── chat.go            # /v1/chat/completions
│   │   │   ├── responses.go       # /v1/responses
│   │   │   └── models.go          # /v1/models
│   │   ├── api/                   # 管理 API
│   │   │   ├── users.go
│   │   │   ├── keys.go
│   │   │   ├── providers.go
│   │   │   └── ...
│   │   └── middleware/
│   │       ├── auth.go
│   │       ├── cors.go
│   │       ├── logger.go
│   │       └── recovery.go
│   │
│   └── pkg/                       # 内部工具包
│       ├── logger/
│       ├── errors/
│       ├── validator/
│       └── utils/
│
├── pkg/                           # 可导出的包
│   └── types/                     # 公共类型定义
│
├── scripts/
│   └── migrate/                   # 迁移工具
│
├── docs/                          # 文档
│   ├── REWRITE.md                 # 本文档
│   └── SPEC.md                    # 技术规范
│
├── go.mod
├── go.sum
├── Makefile
└── README.md

四、模块依赖关系

                    ┌─────────────────┐
                    │  cmd/server     │
                    │  (入口)          │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌─────────┐    ┌─────────┐    ┌─────────┐
        │ config  │    │ logger  │    │ database│
        │ (配置)   │    │ (日志)   │    │ (DB连接) │
        └────┬────┘    └────┬────┘    └────┬────┘
             │              │              │
             └──────────────┼──────────────┘
                            ▼
                    ┌───────────────┐
                    │   repository  │
                    │   (数据访问)    │
                    └───────┬───────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
  ┌──────────┐       ┌──────────┐       ┌──────────┐
  │   auth   │       │  cache   │       │  cost    │
  │  (认证)   │       │  (缓存)   │       │ (计费)    │
  └────┬─────┘       └────┬─────┘       └────┬─────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                          ▼
              ┌───────────────────────┐
              │      ratelimit        │
              │       (限流)           │
              └───────────┬───────────┘
                          │
              ┌───────────┼───────────┐
              ▼           ▼           ▼
       ┌──────────┐ ┌──────────┐ ┌──────────┐
       │ breaker  │ │ session  │ │ webhook  │
       │  (熔断)   │ │  (会话)   │ │ (通知)    │
       └────┬─────┘ └────┬─────┘ └────┬─────┘
            │            │            │
            └────────────┼────────────┘
                         ▼
                 ┌───────────────┐
                 │     proxy     │
                 │   (代理核心)    │
                 └───────┬───────┘
                         │
                         ▼
                 ┌───────────────┐
                 │    handler    │
                 │  (HTTP处理器)  │
                 └───────────────┘

五、核心模块映射

Node.js 模块	Go 模块	优先级	复杂度
drizzle/schema.ts	internal/model/	P0	中
lib/auth.ts	internal/service/auth/	P0	低
lib/rate-limit/service.ts	internal/service/ratelimit/	P0	高
lib/circuit-breaker.ts	internal/service/circuitbreaker/	P0	中
lib/session-manager.ts	internal/service/session/	P0	高
v1/_lib/proxy-handler.ts	internal/proxy/handler.go	P0	高
v1/_lib/proxy/forwarder.ts	internal/proxy/forwarder.go	P0	高
v1/_lib/proxy/guard-pipeline.ts	internal/proxy/guard/	P0	中
lib/utils/cost-calculation.ts	internal/service/cost/	P1	低
lib/cache/provider-cache.ts	internal/service/cache/	P1	低
lib/notification/	internal/service/notification/	P2	中
lib/redis/lua-scripts.ts	internal/service/ratelimit/lua_scripts.go	P0	中

六、分阶段实现计划

Phase 1：基础设施 (Week 1) [已完成]

序号	任务	对应 Node.js	状态
1.1	项目初始化 (go mod, Makefile)	-	已完成
1.2	config/ 配置加载	lib/config/	已完成
1.3	pkg/logger/ 日志	lib/logger.ts	已完成
1.4	database/postgres.go	drizzle/db.ts	已完成
1.5	database/redis.go	lib/redis/	已完成
1.6	model/ 数据模型	drizzle/schema.ts	已完成
1.7	pkg/errors/ 错误处理	lib/error-*	已完成

交付物: 可运行的空服务，连接 PostgreSQL + Redis

Phase 2：数据访问层 (Week 2) ✅ 已完成

序号	任务	对应 Node.js	状态
2.1	repository/user_repo.go	repository/user.ts	✅ 已完成
2.2	repository/key_repo.go	repository/key.ts	✅ 已完成
2.3	repository/provider_repo.go	repository/provider.ts	✅ 已完成
2.4	repository/statistics_repo.go	repository/statistics.ts	✅ 已完成
2.5	repository/price_repo.go	actions/model-prices.ts	✅ 已完成

交付物: 完整的 CRUD 操作层

Phase 3：核心服务层 (Week 3-4)

序号	任务	对应 Node.js	状态
3.1	service/auth/ API Key 认证	lib/auth.ts	待开始
3.2	service/cache/ 供应商缓存	lib/cache/	待开始
3.3	service/cost/ Token 计费	lib/utils/cost-calculation.ts	待开始
3.4	service/ratelimit/ 多维度限流	lib/rate-limit/	待开始
3.5	service/circuitbreaker/ 熔断器	lib/circuit-breaker.ts	待开始
3.6	service/session/ 会话管理	lib/session-manager.ts	待开始

交付物: 核心业务逻辑可独立测试

Phase 4：代理核心 (Week 5-6) ⭐ 最重要

序号	任务	对应 Node.js	状态
4.1	proxy/session.go ProxySession	v1/_lib/proxy/session.ts	待开始
4.2	proxy/guard/ Guard 链	v1/_lib/proxy/guards/	待开始
4.3	proxy/provider_selector.go	v1/_lib/proxy/provider-selector.ts	待开始
4.4	proxy/forwarder.go 请求转发	v1/_lib/proxy/forwarder.ts	待开始
4.5	proxy/sse.go SSE 流处理	lib/utils/sse.ts	待开始
4.6	proxy/handler.go 主处理器	v1/_lib/proxy-handler.ts	待开始
4.7	proxy/converter/ 格式转换	v1/_lib/converters/	待开始

交付物: 完整的代理功能，可处理 Claude/OpenAI 请求

Phase 5：HTTP 层 (Week 7)

序号	任务	对应 Node.js	状态
5.1	handler/middleware/ 中间件	各中间件	待开始
5.2	handler/v1/messages.go	/v1/messages	待开始
5.3	handler/v1/chat.go	/v1/chat/completions	待开始
5.4	handler/v1/responses.go	/v1/responses	待开始
5.5	handler/v1/models.go	/v1/models	待开始
5.6	handler/api/ 管理 API	/api/actions/*	待开始

交付物: 完整的 API 端点，兼容现有客户端

Phase 6：辅助功能 (Week 8+)

序号	任务	对应 Node.js	状态
6.1	service/notification/ 通知	lib/notification/	待开始
6.2	Webhook 渲染器	lib/webhook/renderers/	待开始
6.3	敏感词检测	lib/sensitive-word-detector.ts	待开始
6.4	请求过滤	lib/request-filter-engine.ts	待开始

七、测试与验证策略

7.1 测试层级

┌─────────────────────────────────────────────────┐
│               E2E 测试 (端到端)                   │
│   - 完整 API 请求流程                            │
│   - 与 Node.js 版本行为对比                       │
├─────────────────────────────────────────────────┤
│              集成测试 (Integration)              │
│   - Repository + 真实数据库                      │
│   - Service + Redis                             │
│   - HTTP Handler + 完整服务栈                    │
├─────────────────────────────────────────────────┤
│               单元测试 (Unit)                    │
│   - 纯函数逻辑                                   │
│   - Mock 外部依赖                                │
│   - 边界条件覆盖                                 │
└─────────────────────────────────────────────────┘

7.2 关键验证点

模块	验证内容	方法
代理 API	请求/响应格式兼容性	对比测试
SSE 流	流式响应正确性	抓包对比
限流	多维度限流精度	压力测试
熔断器	状态切换正确性	故障注入
成本计算	计费精度	单元测试
并发	高并发稳定性	压力测试

7.3 兼容性测试脚本

# 同时运行两个服务，对比响应
# scripts/compare_test.sh

NODE_URL="http://localhost:3000"
GO_URL="http://localhost:8080"

# 对比 API 响应
curl -s "$NODE_URL/v1/models" | jq -S > /tmp/node_models.json
curl -s "$GO_URL/v1/models" | jq -S > /tmp/go_models.json
diff /tmp/node_models.json /tmp/go_models.json

7.4 灰度发布策略

阶段 1: 开发测试 (Dev)
  └── 仅内部测试环境

阶段 2: 影子模式 (Shadow)
  └── 复制生产流量到 Go 服务，不返回响应
  └── 对比日志和指标

阶段 3: 金丝雀发布 (Canary)
  └── 5% → 20% → 50% 流量切换

阶段 4: 全量发布 (Production)
  └── 100% 流量切换
  └── 保留 Node.js 服务作为回滚备份

八、API 兼容性要求

目标: 100% 兼容现有 Node.js 版本的 API

代理 API

端点	方法	说明
/v1/messages	POST	Claude 原生 API
/v1/chat/completions	POST	OpenAI 兼容 API
/v1/responses	POST	Codex API
/v1/models	GET	模型列表

管理 API

端点	方法	说明
/api/actions/users/*	CRUD	用户管理
/api/actions/keys/*	CRUD	Key 管理
/api/actions/providers/*	CRUD	供应商管理
/api/actions/statistics/*	GET	统计数据

九、开发规范

9.1 代码风格

遵循 Go 官方代码规范
使用 golangci-lint 进行代码检查
错误处理使用 errors.Wrap 添加上下文
日志使用结构化字段

9.2 命名规范

包名使用小写单词
接口名以 er 结尾 (如 UserRepository)
私有方法/变量使用小写开头
常量使用驼峰式

9.3 测试规范

每个包必须有对应的 _test.go 文件
测试函数命名: Test<Function>_<Scenario>
使用 table-driven tests
Mock 使用 mockgen 生成

十、风险与应对

风险	影响	应对策略
SSE 流处理复杂	高	详细研究 Gin SSE 实现，增加测试覆盖
Lua 脚本迁移	中	保持与 Node.js 版本一致的脚本逻辑
供应商 API 变更	低	使用 adapter 模式隔离变更
性能回归	中	建立基准测试，持续监控

十一、里程碑检查点

M1: 基础设施完成，服务可启动
M2: Repository 层完成，可进行 CRUD 操作
M3: 核心服务完成，限流/熔断可工作
M4: 代理核心完成，可转发 API 请求
M5: HTTP 层完成，API 100% 兼容
M6: 辅助功能完成，通知系统可用
M7: 测试完成，准备灰度发布

REWRITE.md 19 KB Permalink Cronologia Originale