# sub2api 项目开发指南 > 本文档记录项目环境配置、开发规范和常见问题，供 Claude Code 和团队成员参考。 ## 一、项目基本信息 | 项目 | 说明 | |------|------| | **远程仓库** | https://www.tksea.top/pham/tokens-reef | | **技术栈** | Go 后端 (Ent ORM + Gin) + Vue3 前端 | | **数据库** | PostgreSQL 15+ + Redis 7+ | | **包管理** | 后端: go modules, 前端: npm | --- ## 二、项目规范 ### 2.1 代码规范 #### 后端目录结构 ``` backend/internal/ ├── config/ # 配置管理 (viper) ├── domain/ # 领域模型 ├── handler/ # HTTP 处理器 ├── service/ # 业务逻辑层 ├── repository/ # 数据访问层 ├── middleware/ # HTTP 中间件 ├── pkg/ # 内部工具包 ├── util/ # 工具函数 ├── testutil/ # 测试工具和 fixtures └── web/ # 前端嵌入 ``` #### 前端目录结构 ``` frontend/src/ ├── api/ # API 调用封装 ├── components/ # 可复用组件 ├── composables/ # Vue 组合式函数 ├── stores/ # Pinia 状态管理 ├── views/ # 页面视图 ├── types/ # TypeScript 类型定义 ├── utils/ # 工具函数 └── i18n/ # 国际化 ``` ### 2.2 命名约定 | 类型 | 约定 | 示例 | |------|------|------| | 接口 | PascalCase + 后缀 | `UserService`, `AccountRepository` | | 实现 | camelCase + 后缀 | `userService`, `accountRepository` | | 测试文件 | 源文件_test.go | `user_service_test.go` | | 测试 Stub | stub + 名称 | `stubUserRepo` | | 前端组件 | PascalCase | `UserList.vue` | | 前端测试 | __tests__/xxx.spec.ts | `UserList.spec.ts` | ### 2.3 Git 提交规范 **格式**: ``` (): ``` **Type 类型**: - `feat`: 新功能 - `fix`: Bug 修复 - `docs`: 文档更新 - `refactor`: 重构 - `test`: 测试相关 - `chore`: 构建/工具/清理 - `security`: 安全修复 **示例**: ``` fix(config): resolve Windows path resolution issue - Add optional configPaths parameter to load() - Use t.TempDir() for test isolation ``` ### 2.4 测试规范 **后端测试**: ```bash # 单元测试 go test -tags=unit ./... # 集成测试（需要数据库） go test -tags=integration ./... # 特定包 go test -tags=unit ./internal/service/ -v ``` **前端测试**: ```bash # 运行测试 npm run test:run # 监听模式 npm run test # 覆盖率 npm run test:coverage ``` **测试原则**: 1. 测试文件与源码同目录（Go: `*_test.go`, Vue: `__tests__/`） 2. 使用 `t.TempDir()` 创建隔离临时目录 3. 清理资源：关闭文件、释放锁、重置全局状态 4. Windows 兼容：注意路径、pipe、文件锁差异 --- ## 三、本地环境配置 ### 3.1 PostgreSQL | 配置项 | 值 | |--------|-----| | 端口 | 5432 | | 数据库 | sub2api | | 用户 | sub2api / sub2api | | 超级用户 | postgres / postgres | ### 3.2 Redis | 配置项 | 值 | |--------|-----| | 端口 | 6379 | | 密码 | 无 | ### 3.3 开发工具 ```bash # golangci-lint go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest # Ent 代码生成 go install entgo.io/ent/cmd/ent@latest ``` --- ## 四、常用命令 ### 4.1 后端命令 ```bash # 运行服务 go run ./cmd/server/ # 构建 go build -o bin/server ./cmd/server/ # 生成 Ent 代码（修改 schema 后必须执行） go generate ./ent # 单元测试 go test -tags=unit ./... # 集成测试 go test -tags=integration ./... # Lint 检查 golangci-lint run ./... # 检查所有 go test -tags=unit ./... && golangci-lint run ./... ``` ### 4.2 前端命令 ```bash # 安装依赖 npm install # 开发服务器 npm run dev # 构建 npm run build # 类型检查 npx vue-tsc --noEmit # 测试 npm run test:run # Lint npm run lint ``` ### 4.3 数据库命令 ```bash # 连接数据库 psql -U sub2api -h 127.0.0.1 -d sub2api # 执行迁移 psql -U sub2api -h 127.0.0.1 -d sub2api -f migrations/xxx.sql # 查看表结构 \dt \d table_name ``` --- ## 五、常见问题 ### 5.1 Ent Schema 修改后不生效 **原因**: Ent 是代码生成工具，修改 schema 后需要重新生成 **解决**: ```bash cd backend go generate ./ent git add ent/ ``` ### 5.2 接口新增方法后编译失败 **原因**: 所有实现该接口的 mock/stub 都需要补全新方法 **解决**: ```bash # 搜索所有 stub grep -r "type.*Stub.*struct" internal/ grep -r "type.*Mock.*struct" internal/ # 逐一补全新方法 ``` ### 5.3 Windows 上测试超时 **原因**: Windows pipe 的 Sync() 会阻塞 **解决**: 先关闭 write end 再调用 Sync ```go _ = stdoutW.Close() _ = stderrW.Close() Sync() ``` ### 5.4 配置测试读取了错误的文件 **原因**: viper 搜索路径包含意外的配置文件 **解决**: 使用可选参数传入测试目录 ```go // 生产 load(false) // 测试 load(false, t.TempDir()) ``` ### 5.5 PowerShell 变量转义问题 **问题**: bcrypt hash 中的 `$` 被解析为变量 **解决**: 使用文件执行 SQL ```bash echo "INSERT INTO users ... VALUES ('\$2a\$10\$...')" > temp.sql psql -f temp.sql ``` ### 5.6 psql 不支持中文路径 **解决**: 复制到英文路径再执行 ```bash cp "D:\中文\file.sql" "C:\temp.sql" psql -f "C:\temp.sql" ``` ### 5.7 PostgreSQL 密码重置 1. 修改 `pg_hba.conf`，将 `scram-sha-256` 改为 `trust` 2. 重启服务: `Restart-Service postgresql-x64-16` 3. 无密码登录重置密码 4. 改回 `scram-sha-256` 并重启 --- ## 六、PR 检查清单提交前务必验证： - [ ] `go test -tags=unit ./...` 通过 - [ ] `go test -tags=integration ./...` 通过（如适用） - [ ] `golangci-lint run ./...` 无新增问题 - [ ] `npm run test:run` 通过 - [ ] `npx vue-tsc --noEmit` 无类型错误 - [ ] Ent 生成的代码已提交（如改了 schema） - [ ] 测试 stub 已更新（如改了 interface） - [ ] 无敏感信息泄露 --- ## 七、CI/CD 流水线 | Workflow | 触发条件 | 检查内容 | |----------|----------|----------| | backend-ci.yml | push, PR | 单元测试 + Lint | | security-scan.yml | push, PR, 周一 | 安全扫描 | | release.yml | tag v* | 构建发布 | --- ## 八、参考资源 - [项目复盘总结](docs/PROJECT_REVIEW.md) - [审查报告](docs/reports/) - [Ent 文档](https://entgo.io/) - [Vue 3 文档](https://vuejs.org/) - [Gin 文档](https://gin-gonic.com/)