494 lines
10 KiB
Markdown
494 lines
10 KiB
Markdown
# 开发指南
|
||
|
||
## 1. 环境要求
|
||
|
||
### 1.1 必需软件
|
||
|
||
| 软件 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Node.js | 20.x LTS | 运行时环境 |
|
||
| npm | 10.x | 包管理器 |
|
||
| Docker | 24.x+ | 容器化 |
|
||
| Docker Compose | 2.x | 容器编排 |
|
||
| PostgreSQL | 15.x | 数据库 |
|
||
| Redis | 7.x | 缓存 |
|
||
|
||
### 1.2 推荐 IDE
|
||
|
||
- **VS Code** (推荐)
|
||
- 插件: ESLint, Prettier, Prisma, TypeScript
|
||
- **WebStorm**
|
||
- **Cursor**
|
||
|
||
## 2. 项目设置
|
||
|
||
### 2.1 克隆项目
|
||
|
||
```bash
|
||
cd backend/services
|
||
git clone <repository-url> reporting-service
|
||
cd reporting-service
|
||
```
|
||
|
||
### 2.2 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 2.3 环境配置
|
||
|
||
创建 `.env.development` 文件:
|
||
|
||
```bash
|
||
cp .env.example .env.development
|
||
```
|
||
|
||
编辑 `.env.development`:
|
||
|
||
```env
|
||
# Application
|
||
NODE_ENV=development
|
||
PORT=3000
|
||
|
||
# Database
|
||
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/rwadurian_reporting?schema=public
|
||
|
||
# Redis
|
||
REDIS_HOST=localhost
|
||
REDIS_PORT=6379
|
||
|
||
# JWT
|
||
JWT_SECRET=your-development-secret-key
|
||
|
||
# External Services (可选)
|
||
LEADERBOARD_SERVICE_URL=http://localhost:3001
|
||
PLANTING_SERVICE_URL=http://localhost:3002
|
||
```
|
||
|
||
### 2.4 数据库设置
|
||
|
||
启动 PostgreSQL (使用 Docker):
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name reporting-postgres \
|
||
-e POSTGRES_USER=postgres \
|
||
-e POSTGRES_PASSWORD=postgres \
|
||
-e POSTGRES_DB=rwadurian_reporting \
|
||
-p 5432:5432 \
|
||
postgres:15-alpine
|
||
```
|
||
|
||
生成 Prisma Client:
|
||
|
||
```bash
|
||
npx prisma generate
|
||
```
|
||
|
||
同步数据库 Schema:
|
||
|
||
```bash
|
||
npx prisma db push
|
||
```
|
||
|
||
(可选) 填充种子数据:
|
||
|
||
```bash
|
||
npm run prisma:seed
|
||
```
|
||
|
||
### 2.5 启动 Redis
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name reporting-redis \
|
||
-p 6379:6379 \
|
||
redis:7-alpine
|
||
```
|
||
|
||
## 3. 开发工作流
|
||
|
||
### 3.1 启动开发服务器
|
||
|
||
```bash
|
||
# 热重载模式
|
||
npm run start:dev
|
||
|
||
# 调试模式
|
||
npm run start:debug
|
||
```
|
||
|
||
服务启动后访问:
|
||
- API: http://localhost:3000/api/v1
|
||
- Swagger: http://localhost:3000/api (如已启用)
|
||
|
||
### 3.2 常用命令
|
||
|
||
```bash
|
||
# 构建项目
|
||
npm run build
|
||
|
||
# 运行 Lint
|
||
npm run lint
|
||
|
||
# 格式化代码
|
||
npm run format
|
||
|
||
# 运行测试
|
||
npm test
|
||
|
||
# 运行测试 (watch 模式)
|
||
npm run test:watch
|
||
|
||
# 生成测试覆盖率
|
||
npm run test:cov
|
||
|
||
# Prisma Studio (数据库可视化)
|
||
npm run prisma:studio
|
||
```
|
||
|
||
### 3.3 使用 Makefile
|
||
|
||
```bash
|
||
# 查看所有可用命令
|
||
make help
|
||
|
||
# 安装依赖
|
||
make install
|
||
|
||
# 构建项目
|
||
make build
|
||
|
||
# 运行所有测试
|
||
make test
|
||
|
||
# 运行单元测试
|
||
make test-unit
|
||
|
||
# 运行集成测试
|
||
make test-integration
|
||
|
||
# 运行 E2E 测试
|
||
make test-e2e
|
||
|
||
# Docker 测试
|
||
make test-docker-all
|
||
```
|
||
|
||
## 4. 代码规范
|
||
|
||
### 4.1 目录结构规范
|
||
|
||
```
|
||
src/
|
||
├── api/ # API层
|
||
│ ├── controllers/ # 每个资源一个控制器文件
|
||
│ └── dto/
|
||
│ ├── request/ # 请求 DTO
|
||
│ └── response/ # 响应 DTO
|
||
├── application/ # 应用层
|
||
│ ├── commands/ # 每个命令独立目录
|
||
│ │ └── xxx/
|
||
│ │ ├── xxx.command.ts
|
||
│ │ └── xxx.handler.ts
|
||
│ └── queries/ # 每个查询独立目录
|
||
├── domain/ # 领域层
|
||
│ ├── aggregates/ # 每个聚合独立目录
|
||
│ │ └── xxx/
|
||
│ │ ├── index.ts
|
||
│ │ ├── xxx.aggregate.ts
|
||
│ │ └── xxx.spec.ts # 单元测试
|
||
│ ├── value-objects/ # 值对象
|
||
│ │ ├── xxx.vo.ts
|
||
│ │ └── xxx.spec.ts
|
||
│ └── repositories/ # 仅接口定义
|
||
└── infrastructure/ # 基础设施层
|
||
```
|
||
|
||
### 4.2 命名规范
|
||
|
||
**文件命名**:
|
||
- 使用 kebab-case: `report-definition.aggregate.ts`
|
||
- 后缀约定:
|
||
- `.aggregate.ts` - 聚合根
|
||
- `.entity.ts` - 实体
|
||
- `.vo.ts` - 值对象
|
||
- `.service.ts` - 服务
|
||
- `.controller.ts` - 控制器
|
||
- `.dto.ts` - DTO
|
||
- `.spec.ts` - 单元测试
|
||
- `.e2e-spec.ts` - E2E 测试
|
||
- `.integration.spec.ts` - 集成测试
|
||
|
||
**类命名**:
|
||
- 使用 PascalCase
|
||
- 聚合根: `ReportSnapshot`
|
||
- 值对象: `DateRange`
|
||
- 服务: `ReportingApplicationService`
|
||
- 控制器: `ReportController`
|
||
|
||
**接口命名**:
|
||
- 以 `I` 开头: `IReportSnapshotRepository`
|
||
|
||
### 4.3 代码风格
|
||
|
||
**TypeScript 配置** (`tsconfig.json`):
|
||
|
||
```json
|
||
{
|
||
"compilerOptions": {
|
||
"strict": true,
|
||
"strictNullChecks": true,
|
||
"noImplicitAny": true,
|
||
"noUnusedLocals": true,
|
||
"noUnusedParameters": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**ESLint 规则** (关键规则):
|
||
|
||
```javascript
|
||
{
|
||
rules: {
|
||
'@typescript-eslint/explicit-function-return-type': 'warn',
|
||
'@typescript-eslint/no-explicit-any': 'warn',
|
||
'@typescript-eslint/no-unused-vars': 'error',
|
||
'no-console': 'warn'
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.4 领域驱动设计规范
|
||
|
||
**聚合根规则**:
|
||
|
||
```typescript
|
||
// 1. 使用私有属性 + getter
|
||
export class ReportSnapshot {
|
||
private readonly _id: bigint;
|
||
private _snapshotData: SnapshotData;
|
||
|
||
get id(): bigint { return this._id; }
|
||
get snapshotData(): SnapshotData { return this._snapshotData; }
|
||
|
||
// 2. 使用工厂方法创建
|
||
public static create(props: CreateProps): ReportSnapshot {
|
||
const snapshot = new ReportSnapshot(props);
|
||
snapshot.addDomainEvent(new SnapshotCreatedEvent(snapshot));
|
||
return snapshot;
|
||
}
|
||
|
||
// 3. 使用 reconstitute 重建 (不触发事件)
|
||
public static reconstitute(props: ReconstitutionProps): ReportSnapshot {
|
||
return new ReportSnapshot(props);
|
||
}
|
||
|
||
// 4. 业务方法封装状态变更
|
||
public updateData(newData: SnapshotData): void {
|
||
this.validateDataUpdate(newData);
|
||
this._snapshotData = newData;
|
||
this._updatedAt = new Date();
|
||
}
|
||
|
||
// 5. 私有构造函数
|
||
private constructor(props: Props) { ... }
|
||
}
|
||
```
|
||
|
||
**值对象规则**:
|
||
|
||
```typescript
|
||
// 1. 不可变
|
||
export class DateRange {
|
||
private readonly _startDate: Date;
|
||
private readonly _endDate: Date;
|
||
|
||
private constructor(startDate: Date, endDate: Date) {
|
||
this._startDate = startDate;
|
||
this._endDate = endDate;
|
||
Object.freeze(this); // 冻结对象
|
||
}
|
||
|
||
// 2. 工厂方法 + 验证
|
||
public static create(startDate: Date, endDate: Date): DateRange {
|
||
if (startDate > endDate) {
|
||
throw new DomainException('Invalid date range');
|
||
}
|
||
return new DateRange(startDate, endDate);
|
||
}
|
||
|
||
// 3. 实现 equals 方法
|
||
public equals(other: DateRange): boolean {
|
||
return this._startDate.getTime() === other._startDate.getTime() &&
|
||
this._endDate.getTime() === other._endDate.getTime();
|
||
}
|
||
}
|
||
```
|
||
|
||
## 5. Git 工作流
|
||
|
||
### 5.1 分支策略
|
||
|
||
```
|
||
main # 生产分支
|
||
├── develop # 开发分支
|
||
│ ├── feature/xxx # 功能分支
|
||
│ ├── bugfix/xxx # 修复分支
|
||
│ └── refactor/xxx # 重构分支
|
||
└── release/x.x.x # 发布分支
|
||
```
|
||
|
||
### 5.2 提交规范
|
||
|
||
使用 Conventional Commits:
|
||
|
||
```bash
|
||
# 格式
|
||
<type>(<scope>): <subject>
|
||
|
||
# 示例
|
||
feat(report): add daily report generation
|
||
fix(export): resolve Excel formatting issue
|
||
refactor(domain): extract value object for date range
|
||
test(e2e): add report generation tests
|
||
docs(api): update API documentation
|
||
```
|
||
|
||
**Type 类型**:
|
||
- `feat`: 新功能
|
||
- `fix`: Bug 修复
|
||
- `refactor`: 代码重构
|
||
- `test`: 测试相关
|
||
- `docs`: 文档更新
|
||
- `chore`: 构建/配置变更
|
||
- `perf`: 性能优化
|
||
|
||
### 5.3 PR 规范
|
||
|
||
PR 标题遵循提交规范，PR 描述需包含:
|
||
|
||
```markdown
|
||
## Summary
|
||
简要说明本次变更内容
|
||
|
||
## Changes
|
||
- 变更点 1
|
||
- 变更点 2
|
||
|
||
## Test Plan
|
||
- [ ] 单元测试通过
|
||
- [ ] 集成测试通过
|
||
- [ ] 手动测试场景
|
||
```
|
||
|
||
## 6. 调试技巧
|
||
|
||
### 6.1 VS Code 调试配置
|
||
|
||
`.vscode/launch.json`:
|
||
|
||
```json
|
||
{
|
||
"version": "0.2.0",
|
||
"configurations": [
|
||
{
|
||
"type": "node",
|
||
"request": "launch",
|
||
"name": "Debug NestJS",
|
||
"runtimeArgs": ["--nolazy", "-r", "ts-node/register"],
|
||
"args": ["${workspaceFolder}/src/main.ts"],
|
||
"sourceMaps": true,
|
||
"envFile": "${workspaceFolder}/.env.development"
|
||
},
|
||
{
|
||
"type": "node",
|
||
"request": "launch",
|
||
"name": "Debug Jest Tests",
|
||
"program": "${workspaceFolder}/node_modules/.bin/jest",
|
||
"args": ["--runInBand", "--watchAll=false"],
|
||
"console": "integratedTerminal",
|
||
"internalConsoleOptions": "neverOpen"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 6.2 日志调试
|
||
|
||
```typescript
|
||
import { Logger } from '@nestjs/common';
|
||
|
||
@Injectable()
|
||
export class ReportingApplicationService {
|
||
private readonly logger = new Logger(ReportingApplicationService.name);
|
||
|
||
async generateReport(dto: GenerateReportDto) {
|
||
this.logger.debug(`Generating report: ${dto.reportCode}`);
|
||
this.logger.log(`Report generated successfully`);
|
||
this.logger.warn(`Performance warning: slow query`);
|
||
this.logger.error(`Failed to generate report`, error.stack);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.3 Prisma 调试
|
||
|
||
启用查询日志:
|
||
|
||
```typescript
|
||
// prisma.service.ts
|
||
const prisma = new PrismaClient({
|
||
log: [
|
||
{ level: 'query', emit: 'event' },
|
||
{ level: 'error', emit: 'stdout' },
|
||
{ level: 'warn', emit: 'stdout' },
|
||
],
|
||
});
|
||
|
||
prisma.$on('query', (e) => {
|
||
console.log('Query: ' + e.query);
|
||
console.log('Params: ' + e.params);
|
||
console.log('Duration: ' + e.duration + 'ms');
|
||
});
|
||
```
|
||
|
||
## 7. 常见问题
|
||
|
||
### Q: Prisma Client 未生成
|
||
|
||
```bash
|
||
npx prisma generate
|
||
```
|
||
|
||
### Q: 数据库连接失败
|
||
|
||
1. 检查 PostgreSQL 是否运行: `docker ps`
|
||
2. 检查 DATABASE_URL 环境变量
|
||
3. 检查网络连接和端口
|
||
|
||
### Q: 测试失败 - 表不存在
|
||
|
||
```bash
|
||
# 推送 schema 到测试数据库
|
||
DATABASE_URL="postgresql://..." npx prisma db push
|
||
```
|
||
|
||
### Q: TypeScript 编译错误
|
||
|
||
```bash
|
||
# 清理并重新构建
|
||
rm -rf dist
|
||
npm run build
|
||
```
|
||
|
||
### Q: 端口被占用
|
||
|
||
```bash
|
||
# 查找占用端口的进程
|
||
lsof -i :3000
|
||
# 或在 Windows
|
||
netstat -ano | findstr :3000
|
||
```
|