191 lines
3.9 KiB
Markdown
191 lines
3.9 KiB
Markdown
# 路由装饰器使用指南（TC39 标准）
|
||
|
||
本项目使用符合 **TC39 Stage 3 提案**的标准装饰器语法，提供现代化的路由定义方式。
|
||
|
||
## TC39 装饰器优势
|
||
|
||
- ✅ **标准化**：符合 ECMAScript 官方标准提案
|
||
- ✅ **类型安全**：完整的 TypeScript 类型支持
|
||
- ✅ **性能优化**：无需 reflect-metadata 依赖
|
||
- ✅ **未来兼容**：随着标准发展自动获得浏览器支持
|
||
|
||
## 快速开始
|
||
|
||
### 1. 创建控制器
|
||
|
||
```typescript
|
||
import type { Context } from 'koa';
|
||
import { Controller, Get, Post, Put, Delete } from '../decorators/route.ts';
|
||
import { BusinessError } from '../middlewares/exception.ts';
|
||
|
||
@Controller('/api-prefix') // 控制器路由前缀
|
||
export class MyController {
|
||
|
||
@Get('/users')
|
||
async getUsers(ctx: Context) {
|
||
// 直接返回数据，自动包装成统一响应格式
|
||
return { users: [] };
|
||
}
|
||
|
||
@Post('/users')
|
||
async createUser(ctx: Context) {
|
||
const userData = (ctx.request as any).body;
|
||
// 业务逻辑处理...
|
||
return { id: 1, ...userData };
|
||
}
|
||
|
||
@Put('/users/:id')
|
||
async updateUser(ctx: Context) {
|
||
const { id } = ctx.params;
|
||
const userData = (ctx.request as any).body;
|
||
// 业务逻辑处理...
|
||
return { id, ...userData };
|
||
}
|
||
|
||
@Delete('/users/:id')
|
||
async deleteUser(ctx: Context) {
|
||
const { id } = ctx.params;
|
||
// 业务逻辑处理...
|
||
return { success: true };
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 注册控制器
|
||
|
||
在 `middlewares/router.ts` 的 `registerDecoratorRoutes()` 方法中添加你的控制器：
|
||
|
||
```typescript
|
||
this.routeScanner.registerControllers([
|
||
ApplicationController,
|
||
UserController,
|
||
MyController // 添加你的控制器
|
||
]);
|
||
```
|
||
|
||
## 可用装饰器
|
||
|
||
### HTTP方法装饰器（TC39 标准）
|
||
|
||
- `@Get(path)` - GET 请求
|
||
- `@Post(path)` - POST 请求
|
||
- `@Put(path)` - PUT 请求
|
||
- `@Delete(path)` - DELETE 请求
|
||
- `@Patch(path)` - PATCH 请求
|
||
|
||
### 控制器装饰器（TC39 标准）
|
||
|
||
- `@Controller(prefix)` - 控制器路由前缀
|
||
|
||
## TC39 装饰器特性
|
||
|
||
### 1. 标准语法
|
||
|
||
```typescript
|
||
// TC39 标准装饰器使用 addInitializer
|
||
@Get('/users')
|
||
async getUsers(ctx: Context) {
|
||
return userData;
|
||
}
|
||
```
|
||
|
||
### 2. 类型安全
|
||
|
||
```typescript
|
||
// 完整的 TypeScript 类型检查
|
||
@Controller('/api')
|
||
export class ApiController {
|
||
@Get('/health')
|
||
healthCheck(): { status: string } {
|
||
return { status: 'ok' };
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 无外部依赖
|
||
|
||
```typescript
|
||
// 不再需要 reflect-metadata
|
||
// 使用内置的 WeakMap 存储元数据
|
||
```
|
||
|
||
## 配置要求
|
||
|
||
### TypeScript 配置
|
||
|
||
```json
|
||
{
|
||
"compilerOptions": {
|
||
"experimentalDecorators": false, // 关闭实验性装饰器
|
||
"emitDecoratorMetadata": false, // 关闭元数据发射
|
||
"target": "ES2022", // 目标 ES2022+
|
||
"useDefineForClassFields": false // 兼容装饰器行为
|
||
}
|
||
}
|
||
```
|
||
|
||
### 依赖
|
||
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
// 无需 reflect-metadata
|
||
}
|
||
}
|
||
```
|
||
|
||
## 路径拼接规则
|
||
|
||
最终的API路径 = 全局前缀 + 控制器前缀 + 方法路径
|
||
|
||
例如：
|
||
|
||
- 全局前缀：`/api`
|
||
- 控制器前缀：`/user`
|
||
- 方法路径：`/list`
|
||
- 最终路径：`/api/user/list`
|
||
|
||
## 响应格式
|
||
|
||
控制器方法只需要返回数据，系统会自动包装成统一响应格式：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "操作成功",
|
||
"data": { /* 控制器返回的数据 */ },
|
||
"timestamp": 1693478400000
|
||
}
|
||
```
|
||
|
||
## 异常处理
|
||
|
||
可以抛出 `BusinessError` 来返回业务异常：
|
||
|
||
```typescript
|
||
import { BusinessError } from '../middlewares/exception.ts';
|
||
|
||
@Get('/users/:id')
|
||
async getUser(ctx: Context) {
|
||
const { id } = ctx.params;
|
||
|
||
if (!id) {
|
||
throw new BusinessError('用户ID不能为空', 1001, 400);
|
||
}
|
||
|
||
// 正常业务逻辑...
|
||
return userData;
|
||
}
|
||
```
|
||
|
||
## 现有路由
|
||
|
||
### UserController
|
||
|
||
- `GET /api/user/list` - 获取用户列表
|
||
- `GET /api/user/detail/:id` - 获取用户详情
|
||
- `POST /api/user` - 创建用户
|
||
- `PUT /api/user/:id` - 更新用户
|
||
- `DELETE /api/user/:id` - 删除用户
|
||
- `GET /api/user/search` - 搜索用户
|