pham/tokens-reef
2
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
686454bf2280f42acf0116d5e9ae85551a3cd269
tokens-reef/DEV_GUIDE.md
User 686454bf22
Some checks failed
CI / test (push) Has been cancelled
Details
CI / golangci-lint (push) Has been cancelled
Details
Security Scan / backend-security (push) Has been cancelled
Details
Security Scan / frontend-security (push) Has been cancelled
Details
docs: add project review and update development guide 
- 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
2026-04-13 06:44:25 +08:00

6.3 KiB
Raw Blame History

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 测试规范

后端测试:

# 单元测试
go test -tags=unit ./...

# 集成测试（需要数据库）
go test -tags=integration ./...

# 特定包
go test -tags=unit ./internal/service/ -v

前端测试:

# 运行测试
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 开发工具

# 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 后端命令

# 运行服务
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 前端命令

# 安装依赖
npm install

# 开发服务器
npm run dev

# 构建
npm run build

# 类型检查
npx vue-tsc --noEmit

# 测试
npm run test:run

# Lint
npm run lint

4.3 数据库命令

# 连接数据库
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 后需要重新生成

解决:

cd backend
go generate ./ent
git add ent/

5.2 接口新增方法后编译失败

原因: 所有实现该接口的 mock/stub 都需要补全新方法

解决:

# 搜索所有 stub
grep -r "type.*Stub.*struct" internal/
grep -r "type.*Mock.*struct" internal/

# 逐一补全新方法

5.3 Windows 上测试超时

原因: Windows pipe 的 Sync() 会阻塞

解决: 先关闭 write end 再调用 Sync

_ = stdoutW.Close()
_ = stderrW.Close()
Sync()

5.4 配置测试读取了错误的文件

原因: viper 搜索路径包含意外的配置文件

解决: 使用可选参数传入测试目录

// 生产
load(false)

// 测试
load(false, t.TempDir())

5.5 PowerShell 变量转义问题

问题: bcrypt hash 中的 $ 被解析为变量

解决: 使用文件执行 SQL

echo "INSERT INTO users ... VALUES ('\$2a\$10\$...')" > temp.sql
psql -f temp.sql

5.6 psql 不支持中文路径

解决: 复制到英文路径再执行

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* 构建发布

八、参考资源

Reference in New Issue View Git Blame Copy Permalink