dc92194b2b
- DEV_GUIDE.md: Add E2E test pitfalls (坑12-15) and Gitea repo info - CLAUDE.md: Add project experience summary and Gitea remote - MEMORY.md: Update with all fixed issues (P0/P1/E2E) - docs/PROJECT_EXPERIENCE.md: New comprehensive experience doc
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` - 代码审查报告
|