511 lines
16 KiB
Markdown
511 lines
16 KiB
Markdown
# ElysiaAPI开发流程
|
||
|
||
## 0. 概览
|
||
|
||
这是一个基于 **Bun + Elysia** 的现代化后端API项目，采用TypeScript开发，集成了MySQL、Redis、JWT认证、Swagger文档等功能。
|
||
|
||
- **运行时**：Bun
|
||
- **框架**：Elysia
|
||
- **语言**：TypeScript
|
||
- **数据库**：MySQL + Drizzle ORM
|
||
- **缓存**：Redis
|
||
- **认证**：JWT
|
||
- **测试**：Vitest
|
||
- **文档**：Swagger
|
||
- **日志**：Winston
|
||
- **代码规范**：ESLint + Prettier
|
||
|
||
使用的技术和库
|
||
|
||
- **数据库**：`"mysql2": "^3.14.1"`, `"drizzle-orm": "^0.44.2"`
|
||
- **token验证**：`"jsonwebtoken": "^9.0.2"`
|
||
- **密码加密**：`"bcrypt": "^6.0.0"`
|
||
|
||
## 1. 相关目录结构和描述
|
||
|
||
### 1.0 整体目录结构
|
||
|
||
```
|
||
project/
|
||
├── 📋 配置文件(config/)
|
||
├── 📁 源代码 (src/)
|
||
├───└───config
|
||
├───├───eneities
|
||
├───├───modules
|
||
│ ├───├───auth
|
||
│ ├───├───captcha
|
||
│ ├───├───health
|
||
│ ├───├───test
|
||
│ ├───└───user
|
||
├───├───plugins
|
||
│ ├───├───drizzle
|
||
│ ├───├───email
|
||
│ ├───├───errorHandle
|
||
│ ├───├───jwt
|
||
│ ├───├───logger
|
||
│ ├───├───redis
|
||
│ ├───└───swagger
|
||
├───└───tests
|
||
│ └───demo
|
||
├───type
|
||
├───utils
|
||
├── 📁 文档 (docs/)
|
||
├── 📁 需求文档 (prd/)
|
||
├── 📁 任务管理 (tasks/)
|
||
├── 📁 AI对话记录 (aiChat/)
|
||
├── 📁 数据库迁移 (drizzle/)
|
||
└── 📁 静态资源 (public/)
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `package.json` | 项目依赖和脚本配置 |
|
||
| `tsconfig.json` | TypeScript编译配置 |
|
||
| `tsconfig.test.json` | 测试环境TypeScript配置 |
|
||
| `vitest.config.ts` | Vitest测试框架配置 |
|
||
| `eslint.config.js` | ESLint代码规范配置 |
|
||
| `bunfig.toml` | Bun运行时配置 |
|
||
| `drizzle.config.ts` | Drizzle ORM配置 |
|
||
| `README.md` | 项目说明文档 |
|
||
```
|
||
|
||
### 1.1 接口目录结构
|
||
|
||
```
|
||
src/modules/
|
||
├── index.ts # API总入口：所有的模块文件都由此导出给主程序
|
||
├── [moduleName]/ # 模块目录：每个模块的名称做目录名
|
||
│ ├── [moduleName].docs.md # 接口逻辑规则
|
||
│ ├── [moduleName].schema.ts # Schema定义
|
||
│ ├── [moduleName].response.ts # 响应格式
|
||
│ ├── [moduleName].service.ts # 业务逻辑
|
||
│ ├── [moduleName].controller.ts # 路由控制器
|
||
│ └── [moduleName].test.doc # 测试用例文档
|
||
```
|
||
|
||
### 1.2 接口目录功能
|
||
|
||
- 每个模块目录下的文件，都需要有对应的功能，不能只有docs.md，其他文件缺一不可
|
||
- [moduleName].docs.md：需要包含接口开发的业务逻辑，包括schema的注意点，response格式的注意点，接口的业务流程，分析相关的数据库，性能问题，安全问题等等需要考虑的地方和注意点
|
||
- [moduleName].schema.ts：定义接口的输入参数，包括参数的类型、参数的必填、参数的默认值、参数的描述、参数的示例
|
||
- [moduleName].response.ts：接口返回数据的格式定义文件
|
||
- [moduleName].service.ts：接口的具体业务逻辑方法
|
||
- [moduleName].controller.ts：接口路由定义文件，在这里组合接口的请求方式、参数类型、响应格式
|
||
|
||
### 1.3 插件目录结构
|
||
|
||
```
|
||
src/plugins/
|
||
├── index.ts # 插件总入口
|
||
├── drizzle/ # 数据库ORM插件
|
||
│ ├── drizzle.plugins.ts
|
||
│ ├── drizzle.service.ts
|
||
│ └── README.md
|
||
├── email/ # 邮件插件
|
||
│ ├── email.plugins.ts
|
||
│ ├── email.service.ts
|
||
│ └── README.md
|
||
├── errorHandle/ # 错误处理插件
|
||
│ └── errorHandler.plugins.ts
|
||
├── jwt/ # JWT认证插件
|
||
│ ├── jwt.plugins.ts
|
||
│ └── jwt.service.ts
|
||
├── logger/ # 日志插件
|
||
│ ├── logger.plugins.ts
|
||
│ └── logger.service.ts
|
||
├── redis/ # Redis插件
|
||
│ ├── redis.plugins.ts
|
||
│ └── redis.service.ts
|
||
└── swagger/ # API文档插件
|
||
└── swagger.plugins.ts
|
||
```
|
||
|
||
### 1.4 类型定义 (type/)
|
||
|
||
```
|
||
src/type/
|
||
├── config.type.ts # 配置相关类型
|
||
├── drizzle.type.ts # 数据库相关类型
|
||
├── error.type.ts # 错误相关类型
|
||
├── jwt.type.ts # JWT相关类型
|
||
├── logger.type.ts # 日志相关类型
|
||
├── redis.type.ts # Redis相关类型
|
||
└── email.type.ts # 邮件相关类型
|
||
```
|
||
|
||
### 1.5 工具函数 (utils/)
|
||
|
||
```
|
||
src/utils/
|
||
├── deviceInfo.ts # 设备信息工具
|
||
├── distributedLock.ts # 分布式锁工具
|
||
├── formatFileSize.ts # 文件大小格式化
|
||
├── formatRoute.ts # 路由格式化
|
||
├── jwt.helper.ts # JWT工具函数
|
||
├── mysql.ts # MySQL工具
|
||
├── pagination.ts # 分页请求参数工厂函数工具
|
||
├── randomChalk.ts # 随机颜色工具
|
||
├── redis.ts # Redis工具
|
||
├── responseFormate.ts # 响应统一格式化处理工具
|
||
├── snowflake.ts # 雪花ID生成器
|
||
└── text.ts # 文本处理工具
|
||
```
|
||
|
||
### 1.6 常量定义 (constants/)
|
||
|
||
```
|
||
src/constants/
|
||
├── swaggerTags.ts # Swagger标签定义：所有模块的tag应该集中在此定义
|
||
└── 其他常量
|
||
```
|
||
|
||
### 1.7 数据库实体
|
||
|
||
```
|
||
src/eneities/
|
||
├── index.ts # 实体总入口
|
||
├── customType.ts # 自定义类型
|
||
└── [table].ts # 数据表定义
|
||
```
|
||
|
||
### 1.8 文件命名约定
|
||
|
||
- 模块名使用 **单数形式**：`auth`、`user`、`product`、`order`
|
||
- 文件名格式：`[module].[type].ts`
|
||
- 导出名格式：`[module][类型名]`
|
||
|
||
## 2. Schema（请求参数类型）
|
||
|
||
**主要指请求参数验证工具，不包括响应**
|
||
|
||
### 2.1 Schema定义规范
|
||
|
||
- 一个模块的所有schema都在一个文件中
|
||
- 使用elysia自带的类型共据`t`
|
||
- 参数一定要明确是必填还是选填，是否有默认值
|
||
- 对必要的数据进行转化，如用户名全小写并且去除两端空格
|
||
- 必须有描述和示例参数
|
||
- 导出类型
|
||
- 注意已经存在的工具函数，比如分页有现成的简化工具，且能够统一请求格式
|
||
|
||
### 2.2 特别注意点
|
||
|
||
**必须遵循的命名模式：**
|
||
|
||
- Request类型：`[动作][模块]Request` → `RegisterRequest`
|
||
- Schema名：`[动作][模块]Schema` → `RegisterSchema`
|
||
|
||
### 2.3 代码示例
|
||
|
||
```ts
|
||
/**
|
||
* @file 用户模块Schema定义
|
||
* @author AI Assistant
|
||
* @date 2024-12-19
|
||
* @lastEditor AI Assistant
|
||
* @lastEditTime 2025-01-07
|
||
* @description 定义用户模块的Schema，包括获取当前用户信息、用户列表查询等
|
||
*/
|
||
|
||
import { t, type Static } from 'elysia';
|
||
import { createQuerySchema } from '@/utils/pagination';
|
||
|
||
/**
|
||
* 用户列表查询参数Schema
|
||
* @description 用户列表查询的请求参数验证规则
|
||
*/
|
||
export const UserListQuerySchema = createQuerySchema(
|
||
t.Object({
|
||
// 用户特有参数
|
||
keyword: t.Optional(
|
||
t.String({
|
||
minLength: 1,
|
||
maxLength: 100,
|
||
description: '搜索关键词，支持用户名、邮箱模糊搜索',
|
||
examples: ['admin', 'test@example.com'],
|
||
}),
|
||
),
|
||
status: t.Optional(
|
||
t.Union([t.Literal('active'), t.Literal('inactive'), t.Literal('pending')], {
|
||
description: '用户状态筛选',
|
||
examples: ['active', 'inactive', 'pending'],
|
||
}),
|
||
),
|
||
gender: t.Optional(
|
||
t.Union([t.Literal(0), t.Literal(1), t.Literal(2), t.Literal('0'), t.Literal('1'), t.Literal('2')], {
|
||
description: '性别筛选：0-未知，1-男，2-女',
|
||
examples: [0, 1, 2],
|
||
}),
|
||
),
|
||
isRoot: t.Optional(
|
||
t.Boolean({
|
||
description: '是否超级管理员筛选',
|
||
examples: [true, false],
|
||
}),
|
||
),
|
||
}),
|
||
);
|
||
|
||
/** 用户列表查询参数类型 */
|
||
export type UserListQueryRequest = Static<typeof UserListQuerySchema>;
|
||
```
|
||
|
||
## 3. Response（响应数据类型）
|
||
|
||
### 3.1 响应格式定义规范
|
||
|
||
- 使用统一的相应格式工具`responseWrapperSchema`
|
||
- 错误相应只提供示例和描述
|
||
- 导出响应成功类型
|
||
|
||
### 3.2 特别注意点
|
||
|
||
**必须遵循的命名模式：**
|
||
|
||
- Response格式定义：`[动作][模块]Response` → `RegisterResponse`
|
||
- Response成功类型：`[动作][模块]SuccessType ` → `RegisterSuccessType `
|
||
|
||
### 3.3 代码示例
|
||
|
||
```ts
|
||
/**
|
||
* @file 用户模块响应格式定义
|
||
* @author AI Assistant
|
||
* @date 2024-12-19
|
||
* @lastEditor AI Assistant
|
||
* @lastEditTime 2025-01-07
|
||
* @description 定义用户模块的响应格式，包括获取当前用户信息、用户列表查询等
|
||
*/
|
||
|
||
import { t, type Static } from 'elysia';
|
||
import { responseWrapperSchema } from '@/utils/responseFormate';
|
||
import { createPaginationResponseSchema } from '@/utils/pagination';
|
||
|
||
/**
|
||
* 用户列表项Schema
|
||
* @description 用户列表中单个用户的数据结构
|
||
*/
|
||
export const UserListItemSchema = t.Object({
|
||
/** 用户ID */
|
||
id: t.String({
|
||
description: '用户ID（bigint类型以字符串形式返回防止精度丢失）',
|
||
examples: ['1', '2', '3'],
|
||
}),
|
||
/** 用户名 */
|
||
username: t.String({
|
||
description: '用户名',
|
||
examples: ['admin', 'testuser'],
|
||
}),
|
||
|
||
/** 更多字段... */
|
||
|
||
/** 更新时间 */
|
||
updatedAt: t.String({
|
||
description: '更新时间',
|
||
examples: ['2024-12-19T10:30:00Z'],
|
||
}),
|
||
});
|
||
|
||
/**
|
||
* 获取用户列表接口响应组合
|
||
* @description 用于Controller中定义所有可能的响应格式
|
||
*/
|
||
export const GetUserListResponsesSchema = {
|
||
200: responseWrapperSchema(createPaginationResponseSchema(UserListItemSchema)),
|
||
401: responseWrapperSchema(
|
||
t.Object({
|
||
error: t.String({
|
||
description: '认证失败',
|
||
examples: ['未提供有效的认证令牌', '令牌已过期'],
|
||
}),
|
||
}),
|
||
),
|
||
400: responseWrapperSchema(
|
||
t.Object({
|
||
error: t.String({
|
||
description: '参数错误',
|
||
examples: ['分页参数无效', '搜索关键词格式错误'],
|
||
}),
|
||
}),
|
||
),
|
||
500: responseWrapperSchema(
|
||
t.Object({
|
||
error: t.String({
|
||
description: '服务器错误',
|
||
examples: ['内部服务器错误'],
|
||
}),
|
||
}),
|
||
),
|
||
};
|
||
|
||
/** 获取用户列表成功响应数据类型 */
|
||
export type GetUserListSuccessType = Static<(typeof GetUserListResponsesSchema)[200]>;
|
||
```
|
||
|
||
## 4. Service（业务逻辑层）
|
||
|
||
### 4.1 Service层要求
|
||
|
||
- ✅ 所有方法必须有完整的类型注解
|
||
- ✅ 所有方法必须有详细的JSDoc注释
|
||
- ✅ 必须使用统一的响应格式工具
|
||
- ✅ 必须使用统一的错误码
|
||
- ✅ 必须有详细的日志记录，接口有请求响应记录，无需记录每次请求
|
||
- ✅ 需要有完整的错误处理，服务错误有拦截器处理可以不管，只判断逻辑上的错误
|
||
- ✅ 导出单例实例供controller使用
|
||
|
||
### 4.2 注意点
|
||
|
||
- 开发逻辑时，注意数据库实体，必须严格按照数据库字段进行开发，不能出错
|
||
- 更新时间数据库一般会自动天写，不用手动设置或更新
|
||
- 数据库id一般为bigint，注意类型和精度问题
|
||
- 在写入数据时，必要的增加分布式锁
|
||
- 逻辑要清晰，代码要简洁
|
||
|
||
### 4.3 代码示例
|
||
|
||
```ts
|
||
/**
|
||
* @file 用户模块Service层实现
|
||
* @author AI Assistant
|
||
* @date 2024-12-19
|
||
* @lastEditor AI Assistant
|
||
* @lastEditTime 2025-01-07
|
||
* @description 用户模块的业务逻辑实现，包括获取当前用户信息、用户列表查询等
|
||
*/
|
||
|
||
import { Logger } from '@/plugins/logger/logger.service';
|
||
import { db } from '@/plugins/drizzle/drizzle.service';
|
||
import { sysUsers } from '@/eneities';
|
||
import { eq, like, and, desc, asc, sql } from 'drizzle-orm';
|
||
import { successResponse, errorResponse, BusinessError } from '@/utils/responseFormate';
|
||
|
||
import { calculatePagination, normalizePaginationParams } from '@/utils/pagination';
|
||
import type { GetCurrentUserSuccessType, GetUserListSuccessType } from './user.response';
|
||
import type { UserListQueryRequest, UserListItem } from './user.schema';
|
||
|
||
/**
|
||
* 用户服务类
|
||
* @description 处理用户相关的业务逻辑
|
||
*/
|
||
export class UserService {
|
||
/**
|
||
* 获取当前用户信息
|
||
* @param userId 用户ID
|
||
* @returns Promise<GetCurrentUserSuccessType>
|
||
* @throws BusinessError 业务逻辑错误
|
||
* @type API =====================================================================
|
||
*/
|
||
public async getCurrentUser(userId: string): Promise<GetCurrentUserSuccessType> {
|
||
Logger.info(`获取用户信息：${userId}`);
|
||
// 查询用户信息
|
||
const user = await db()
|
||
.select({
|
||
id: sysUsers.id,
|
||
username: sysUsers.username,
|
||
email: sysUsers.email,
|
||
nickname: sysUsers.nickname,
|
||
avatar: sysUsers.avatar,
|
||
mobile: sysUsers.mobile,
|
||
status: sysUsers.status,
|
||
lastLoginAt: sysUsers.lastLoginAt,
|
||
createdAt: sysUsers.createdAt,
|
||
updatedAt: sysUsers.updatedAt,
|
||
})
|
||
.from(sysUsers)
|
||
.where(eq(sysUsers.id, BigInt(userId)))
|
||
.limit(1);
|
||
|
||
if (!user || user.length === 0) {
|
||
Logger.warn(`用户不存在：${userId}`);
|
||
throw new BusinessError(`用户不存在：${userId}`, 404);
|
||
}
|
||
|
||
const userData = user[0]!;
|
||
|
||
Logger.info(`获取用户信息成功：${userId} - ${userData.username}`);
|
||
|
||
return successResponse(
|
||
{
|
||
id: userId, // 使用传入的字符串ID，避免精度丢失
|
||
username: userData.username,
|
||
email: userData.email,
|
||
nickname: userData.nickname,
|
||
avatar: userData.avatar,
|
||
phone: userData.mobile,
|
||
status: userData.status,
|
||
lastLoginAt: userData.lastLoginAt || null,
|
||
createdAt: userData.createdAt,
|
||
updatedAt: userData.updatedAt,
|
||
},
|
||
'获取用户信息成功',
|
||
);
|
||
}
|
||
}
|
||
|
||
// 导出单例实例
|
||
export const userService = new UserService();
|
||
```
|
||
|
||
## 5. Controllers（接口名称接入）
|
||
|
||
### 5.1 Controllers层要求
|
||
|
||
- ✅ 路由方法必须有完整的JSDoc注释
|
||
- ✅ 必须定义完整的response schema
|
||
- ✅ 必须有适当的tags分类
|
||
- ✅ 必须有operationId用于API文档
|
||
- ✅ 错误处理由Service层统一处理
|
||
|
||
### 5.2 Controllers层注意点
|
||
|
||
- 使用service时要简洁，如`({ body }) => authService.register(body),`
|
||
|
||
### 5.3 Controllers层代码示例
|
||
|
||
```ts
|
||
/**
|
||
* 认证控制器
|
||
* @description 处理用户认证相关的HTTP请求
|
||
*/
|
||
export const authController = new Elysia()
|
||
/**
|
||
* 用户注册接口
|
||
* @route POST /api/auth/register
|
||
* @description 用户注册，包含验证码验证、用户名邮箱唯一性检查等
|
||
*/
|
||
.post('/register', ({ body }) => authService.register(body), {
|
||
body: RegisterSchema,
|
||
detail: {
|
||
summary: '用户注册',
|
||
description: '用户注册接口，需要提供用户名、邮箱、密码和验证码',
|
||
tags: [tags.auth],
|
||
operationId: 'registerUser',
|
||
},
|
||
response: RegisterResponsesSchema,
|
||
});
|
||
```
|
||
|
||
## 6. 错误处理
|
||
|
||
### 6.1 错误处理规范
|
||
|
||
- 统一`import { BusinessError } from '@/utils/responseFormate';`引入错误工具抛出错误
|
||
- 错误处理在errorHandle.plugins中统一处理，
|
||
|
||
### 6.2 主动抛出异常示例
|
||
|
||
```typescript
|
||
// ✅ Service层错误处理
|
||
import { BusinessError } from '@/utils/responseFormate';
|
||
|
||
// 抛出业务错误
|
||
throw new BusinessError('消息说明...', 409);
|
||
```
|
||
|
||
## 7. 测试用例文档
|
||
|
||
1. 分模块
|
||
2. 分接口
|
||
3. 测试名称
|
||
4. 场景
|
||
5. 方法
|