hurole/foka-ci

Fork 0

Files

hurole 45047f40aa feat: 标准化响应体

2026-01-11 16:39:59 +08:00

3.9 KiB

Raw Blame History

路由装饰器使用指南（TC39 标准）

本项目使用符合 TC39 Stage 3 提案的标准装饰器语法，提供现代化的路由定义方式。

TC39 装饰器优势

✅ 标准化：符合 ECMAScript 官方标准提案
✅ 类型安全：完整的 TypeScript 类型支持
✅ 性能优化：无需 reflect-metadata 依赖
✅ 未来兼容：随着标准发展自动获得浏览器支持

快速开始

1. 创建控制器

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() 方法中添加你的控制器：

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. 标准语法

// TC39 标准装饰器使用 addInitializer
@Get('/users')
async getUsers(ctx: Context) {
  return userData;
}

2. 类型安全

// 完整的 TypeScript 类型检查
@Controller('/api')
export class ApiController {
  @Get('/health')
  healthCheck(): { status: string } {
    return { status: 'ok' };
  }
}

3. 无外部依赖

// 不再需要 reflect-metadata
// 使用内置的 WeakMap 存储元数据

配置要求

TypeScript 配置

{
  "compilerOptions": {
    "experimentalDecorators": false,  // 关闭实验性装饰器
    "emitDecoratorMetadata": false,   // 关闭元数据发射
    "target": "ES2022",               // 目标 ES2022+
    "useDefineForClassFields": false  // 兼容装饰器行为
  }
}

依赖

{
  "dependencies": {
    // 无需 reflect-metadata
  }
}

路径拼接规则

最终的API路径 = 全局前缀 + 控制器前缀 + 方法路径

例如：

全局前缀：/api
控制器前缀：/user
方法路径：/list
最终路径：/api/user/list

响应格式

控制器方法只需要返回数据，系统会自动包装成统一响应格式：

{
  "code": 0,
  "message": "操作成功",
  "data": { /* 控制器返回的数据 */ },
  "timestamp": 1693478400000
}

异常处理

可以抛出 BusinessError 来返回业务异常：

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 - 搜索用户

3.9 KiB Raw Blame History Unescape Escape