169 lines
4.4 KiB
Markdown
169 lines
4.4 KiB
Markdown
|
# Sub2API 项目经验总结
|
|||
|
|
|
|||
|
|
> 本文档记录项目开发过程中的经验教训、常见问题和解决方案。
|
|||
|
|
|
|||
|
|
## 一、项目架构
|
|||
|
|
|
|||
|
|
### 技术栈
|
|||
|
|
- **后端**：Go + Gin + Ent ORM
|
|||
|
|
- **前端**：Vue 3 + Vite + Pinia + TailwindCSS
|
|||
|
|
- **数据库**：PostgreSQL 16 + Redis
|
|||
|
|
- **包管理**：Go modules + pnpm
|
|||
|
|
|
|||
|
|
### 项目结构
|
|||
|
|
```
|
|||
|
|
sub2api/
|
|||
|
|
├── backend/ # Go 后端
|
|||
|
|
│ ├── cmd/server/ # 主程序入口
|
|||
|
|
│ ├── ent/ # Ent ORM 生成代码
|
|||
|
|
│ ├── internal/
|
|||
|
|
│ │ ├── handler/ # HTTP 处理器
|
|||
|
|
│ │ ├── service/ # 业务逻辑
|
|||
|
|
│ │ ├── repository/ # 数据访问层
|
|||
|
|
│ │ └── pkg/ # 公共包
|
|||
|
|
│ ├── migrations/ # 数据库迁移
|
|||
|
|
│ └── config.yaml # 配置文件
|
|||
|
|
├── frontend/ # Vue 前端
|
|||
|
|
├── tests/ # E2E 测试
|
|||
|
|
└── docs/ # 文档
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 二、Git 仓库管理
|
|||
|
|
|
|||
|
|
### 当前仓库配置
|
|||
|
|
|
|||
|
|
| 远程 | 地址 | 用途 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| origin | https://github.com/phamnazage-jpg/tokens-reef.git | GitHub（代码质量修复） |
|
|||
|
|
| gitea | https://www.tksea.top/pham/tokensea.git | Gitea（主仓库） |
|
|||
|
|
|
|||
|
|
### 常用命令
|
|||
|
|
```bash
|
|||
|
|
# 添加 Gitea 远程
|
|||
|
|
git remote add gitea https://www.tksea.top/pham/tokensea.git
|
|||
|
|
|
|||
|
|
# 强制推送到 Gitea（覆盖）
|
|||
|
|
git push -f gitea main
|
|||
|
|
|
|||
|
|
# 强制推送到 GitHub
|
|||
|
|
git push -f origin main
|
|||
|
|
|
|||
|
|
# 查看远程
|
|||
|
|
git remote -v
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 三、开发常见问题
|
|||
|
|
|
|||
|
|
### 1. E2E 测试问题
|
|||
|
|
|
|||
|
|
#### API 路径错误
|
|||
|
|
- **问题**：测试调用 `/api/v1/keys` 但后端路由是 `/api/v1/api-keys`
|
|||
|
|
- **解决**：将所有路径改为 `/api/v1/api-keys`
|
|||
|
|
|
|||
|
|
#### Payload 格式不匹配
|
|||
|
|
- **余额调整**：使用 `{balance, operation, notes}`
|
|||
|
|
- **Rate Multiplier**：使用 `{entries: [{user_id, rate_multiplier}]}`
|
|||
|
|
|
|||
|
|
#### 测试文件无法提交
|
|||
|
|
- **原因**：`tests` 目录在 `.gitignore` 中
|
|||
|
|
- **解决**：使用 `git add -f tests/` 强制添加
|
|||
|
|
|
|||
|
|
### 2. Go 后端问题
|
|||
|
|
|
|||
|
|
#### Wire 依赖注入
|
|||
|
|
- **修改 wire.go 后**：运行 `go mod tidy` 确保依赖完整
|
|||
|
|
- **生成代码位置**：`cmd/server/wire_gen.go`
|
|||
|
|
|
|||
|
|
#### Interface 新增方法
|
|||
|
|
- **问题**：新增方法后编译失败
|
|||
|
|
- **解决**：所有实现该 interface 的 stub/mock 必须补上新方法
|
|||
|
|
|
|||
|
|
#### Ent Schema 修改
|
|||
|
|
- **命令**：`go generate ./ent`
|
|||
|
|
- **生成文件**：需提交 `ent/` 目录
|
|||
|
|
|
|||
|
|
### 3. 前端问题
|
|||
|
|
|
|||
|
|
#### pnpm-lock.yaml 不同步
|
|||
|
|
- **问题**：CI 的 `pnpm install --frozen-lockfile` 失败
|
|||
|
|
- **解决**：确保 `pnpm-lock.yaml` 同步提交
|
|||
|
|
|
|||
|
|
#### node_modules 冲突
|
|||
|
|
- **解决**：删除后重新安装
|
|||
|
|
```bash
|
|||
|
|
rm -rf node_modules
|
|||
|
|
pnpm install
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 四、代码审查经验
|
|||
|
|
|
|||
|
|
### 审查维度
|
|||
|
|
|
|||
|
|
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 端口
|
|||
|
|
|
|||
|
|
## 五、关键配置
|
|||
|
|
|
|||
|
|
### Windows 开发环境
|
|||
|
|
|
|||
|
|
| 项 | 值 |
|
|||
|
|
|---|---|
|
|||
|
|
| Go 路径 | `D:/Program Files/Go/bin/go.exe` |
|
|||
|
|
| PostgreSQL | `C:\Program Files\PostgreSQL\16\` |
|
|||
|
|
| 测试账号 | lon22@qq.com / admin123 |
|
|||
|
|
| 后端端口 | 8080 |
|
|||
|
|
|
|||
|
|
### 测试环境变量
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# E2E 测试
|
|||
|
|
BASE_URL=http://localhost:8080
|
|||
|
|
TEST_EMAIL=lon22@qq.com
|
|||
|
|
TEST_PASSWORD=admin123
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 六、经验教训
|
|||
|
|
|
|||
|
|
### 1. 测试必须验证真实 API 路径
|
|||
|
|
- 不要假设路由是什么，要去 `routes/*.go` 确认
|
|||
|
|
- E2E 测试调用前先手动 curl 验证
|
|||
|
|
|
|||
|
|
### 2. Payload 必须与后端 DTO 一致
|
|||
|
|
- 查看 handler 中的 struct 定义
|
|||
|
|
- 不要猜测字段名，用 grep 确认
|
|||
|
|
|
|||
|
|
### 3. 提交前务必本地验证
|
|||
|
|
- 编译通过 ≠ 测试通过
|
|||
|
|
- 测试通过 ≠ 功能正常
|
|||
|
|
|
|||
|
|
### 4. 文档要及时更新
|
|||
|
|
- 每次修复问题后更新 MEMORY.md
|
|||
|
|
- 新增坑点更新 DEV_GUIDE.md
|
|||
|
|
- 配置变更更新 CLAUDE.md
|
|||
|
|
|
|||
|
|
## 七、相关文档
|
|||
|
|
|
|||
|
|
- `DEV_GUIDE.md` - 开发指南
|
|||
|
|
- `CLAUDE.md` - Claude Code 配置
|
|||
|
|
- `.workbuddy/memory/MEMORY.md` - 长期记忆
|
|||
|
|
- `REVIEW_REPORT_*.md` - 代码审查报告
|