tokens-reef/docs/PROJECT_EXPERIENCE.md

Sub2API 项目经验总结

本文档记录项目开发过程中的经验教训、常见问题和解决方案。

一、项目架构

技术栈

• 后端：Go + Gin + Ent ORM
• 前端：Vue 3 + Vite + Pinia + TailwindCSS
• 数据库：PostgreSQL 16 + Redis
• 包管理：Go modules + pnpm
• 测试：Vitest (前端) + Playwright (E2E) + Go test

项目结构

sub2api/
├── backend/              # Go 后端
│   ├── cmd/server/       # 主程序入口
│   ├── ent/              # Ent ORM 生成代码
│   ├── internal/
│   │   ├── handler/      # HTTP 处理器
│   │   ├── service/      # 业务逻辑
│   │   ├── repository/    # 数据访问层
│   │   └── pkg/          # 公共包
│   ├── migrations/       # 数据库迁移
│   └── config.yaml       # 配置文件
├── frontend/             # Vue 前端
├── tests/                # E2E 测试 (Playwright)
└── docs/                 # 文档

API 路由结构（关键）

端点	路由	文件位置
用户 API Key	/api/v1/keys	routes/user.go:42
管理员 API Key	/api/v1/admin/api-keys	routes/admin.go:91
用户分组	/api/v1/groups/available	routes/user.go:52
管理员分组	/api/v1/admin/groups	routes/admin.go

注意：用户端是 /keys，管理端是 /api-keys，容易混淆。

二、Git 仓库管理

当前仓库配置

远程	地址	用途
origin	https://github.com/phamnazage-jpg/tokens-reef.git	GitHub（代码质量修复）
gitea	https://www.tksea.top/pham/tokensea.git	Gitea（字节海洋主仓库）

常用命令

# 添加 Gitea 远程
git remote add gitea https://www.tksea.top/pham/tokensea.git

# 推送到 Gitea
git push gitea test-fix-branch

# 推送到 GitHub
git push origin test-fix-branch

# 查看远程
git remote -v

三、开发常见问题

1. E2E 测试问题

API 路径错误（重要）

• 问题：测试调用 /api/v1/api-keys 但后端用户端路由是 /api/v1/keys
• 解决：
  • 用户端：/api/v1/keys
  • 管理员端：/api/v1/admin/api-keys
• 验证方法：查看 routes/user.go 和 routes/admin.go 中的路由注册

Payload 格式不匹配

• 余额调整：使用 {balance, operation, notes}
  • ❌ 错误：{amount, reason}
• Rate Multiplier：使用 {entries: [{user_id, rate_multiplier}]}
  • ❌ 错误：[{model, multiplier}]

测试文件无法提交

• 原因：tests 目录在 .gitignore 中
• 解决：使用 git add -f tests/ 强制添加

2. Go 后端问题

Wire 依赖注入

• 修改 wire.go 后：运行 go mod tidy 确保依赖完整
• 生成代码位置：cmd/server/wire_gen.go

Interface 新增方法

• 问题：新增方法后编译失败
• 解决：所有实现该 interface 的 stub/mock 必须补上新方法
• 示例：admin_service.go 新增方法后，stub_test.go 也需同步更新

Handler 注释与路由不一致

• 问题：注释写 /api/v1/api-keys 但实际是 /api/v1/keys
• 解决：始终以 routes/*.go 中的注册为准更新注释

Ent Schema 修改

• 命令：go generate ./ent
• 生成文件：需提交 ent/ 目录

3. 前端问题

pnpm-lock.yaml 不同步

• 问题：CI 的 pnpm install --frozen-lockfile 失败
• 解决：确保 pnpm-lock.yaml 同步提交

node_modules 冲突

• 解决：删除后重新安装

rm -rf node_modules
pnpm install

测试 Mock 不完整

• 问题：运行时警告 "XXX is not a function"
• 解决：在 vi.mock() 中补充缺失的 mock 函数

四、代码审查经验

审查维度

1. 功能正确性：API 响应是否符合预期
2. 性能：是否有 OOM 风险、缓存策略
3. 安全：敏感信息是否硬编码
4. 测试覆盖：关键路径是否有测试

常见问题级别

级别	标记	说明
P0	🔴	编译失败或致命运行时错误
P1	🟡	功能缺陷或性能问题
P2	🟢	改进建议
挑剔	💭	代码风格/文档问题

修复验证流程

1. 本地构建：go build ./cmd/server
2. 单元测试：go test -short ./...
3. 前端构建：cd frontend && pnpm build
4. 前端测试：cd frontend && pnpm test -- --run
5. E2E 测试：确保后端运行在 8080 端口

本次审查发现的问题及修复

ID	问题	位置	修复
P0-01	sticky_session_test.go 缺少 context	service/sticky_session_test.go	添加 import
P1-01	gateway_service.go defaultMaxLineSize过大	service/gateway_service.go	优化为合理值
P1-03	GetStats 返回硬编码零值	handler/admin/group_handler.go	实现真实数据查询
E2E-01	API Key 路径错误 (24处)	tests/e2e/user-apikey-lifecycle.spec.ts	改为 /api/v1/keys
C-01	Handler注释与路由不一致	handler/api_key_handler.go	更新注释
O-02	getModelStats mock 缺失	frontend/.../UsageView.spec.ts	添加 mock

五、关键配置

Windows 开发环境

项	值
Go 路径	D:/Program Files/Go/bin/go.exe
PostgreSQL	C:\Program Files\PostgreSQL\16\
测试账号	lon22@qq.com / admin123
后端端口	8080
前端端口	5173

测试环境变量

# E2E 测试
BASE_URL=http://localhost:8080
TEST_EMAIL=lon22@qq.com
TEST_PASSWORD=admin123

测试命令

# 后端编译
cd backend && D:/Program\ Files/Go/bin/go.exe build ./...

# 后端测试
cd backend && D:/Program\ Files/Go/bin/go.exe test -short ./...

# 前端测试
cd frontend && pnpm test -- --run

# 前端覆盖测试
cd frontend && pnpm test -- --run --coverage

# E2E 测试
cd tests && npx playwright test --project=chromium

六、经验教训

1. 测试必须验证真实 API 路径

• 不要假设路由是什么，要去 routes/*.go 确认
• E2E 测试调用前先手动 curl 验证
• 用户端 /keys vs 管理端 /api-keys 容易混淆

2. Payload 必须与后端 DTO 一致

• 查看 handler 中的 struct 定义
• 不要猜测字段名，用 grep 确认
• 余额操作使用 balance+operation+notes 不是 amount+reason

3. 提交前务必本地验证

• 编译通过 ≠ 测试通过
• 测试通过 ≠ 功能正常
• 单元测试通过 ≠ E2E 测试通过

4. 文档要及时更新

• 每次修复问题后更新 MEMORY.md
• 新增坑点更新 DEV_GUIDE.md
• 配置变更更新 CLAUDE.md

5. 代码审查重点

• API 路径一致性（handler 注释 vs 实际路由）
• 测试 Mock 完整性
• 敏感信息硬编码检查

七、测试覆盖率

模块	覆盖率	说明
src/api	85%	高覆盖率
src/composables	55%	中等
src/stores	55%	中等
src/views/admin	35%	待提高
src/views/user	20%	待提高
src/views/auth	0%	需补充

八、相关文档

• DEV_GUIDE.md - 开发指南
• CLAUDE.md - Claude Code 配置
• .workbuddy/memory/MEMORY.md - 长期记忆
• REVIEW_REPORT_*.md - 代码审查报告
• COMPREHENSIVE_TEST_REVIEW_*.md - 测试审查报告