686454bf22
- Add comprehensive PROJECT_REVIEW.md with development experience summary - Update DEV_GUIDE.md with standardized conventions and best practices - Move audit reports to docs/reports/ and update .gitignore - Document Windows compatibility issues and solutions - Add PR checklist and testing standards
325 lines
6.3 KiB
Markdown
325 lines
6.3 KiB
Markdown
# 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>(<scope>): <subject>
|
||
|
||
<body>
|
||
```
|
||
|
||
**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/)
|