@fastcar/koa 0.1.21 → 0.1.23

package/README.md

@@ -1,115 +1,453 @@
-# 基于封装koa的web成型框架
+# @fastcar/koa
 
-## 快速安装
+基于 [@fastcar/core](https://github.com/williamDazhangyu/fast-car) 框架的 Koa Web 服务封装组件，提供装饰器驱动的路由定义和中间件管理。
 
+## 目录
+
+- [特性](#特性)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [配置](#配置)
+- [装饰器/API 参考](#装饰器api-参考)
+- [内置中间件](#内置中间件)
+- [示例](#示例)
+- [类型定义](#类型定义)
+- [依赖关系](#依赖关系)
+- [许可证](#许可证)
+
+## 特性
+
+- 🎯 **装饰器驱动**: 使用 TypeScript 装饰器定义路由和中间件
+- 🔌 **模块化中间件**: 支持自定义和内置中间件，按声明顺序加载
+- 🚀 **自动依赖注入**: 集成 @fastcar/core 的 IoC 容器
+- 📁 **静态文件服务**: 内置静态文件和文件上传支持
+- 🛡️ **全局异常处理**: 内置异常捕获中间件
+- 📚 **Swagger 文档**: 支持 API 文档自动生成（需安装 swagger-ui-dist）
+- 🔄 **代理支持**: 内置反向代理中间件
+
+## 安装
+
+```bash
 npm install @fastcar/koa
+# 或
+yarn add @fastcar/koa
+```
+
+### 必需依赖
+
+```bash
+npm install @fastcar/core @fastcar/server koa @koa/router
+```
+
+### 可选依赖
+
+根据功能需要安装：
+
+```bash
+# 文件上传
+npm install @koa/multer multer
+
+# 静态文件服务
+npm install koa-static koa-range koa-mount
+
+# 跨域支持
+npm install koa2-cors
 
-## 基本原理
+# 请求体解析
+npm install @koa/bodyparser koa-body
 
-* 采用@fastcar/core框架，然后将koa包装成一个基础组件进行调用
-* 加载顺序为优先加载自定义中间件->加载自定义路由->启动http服务进行监听
-* 停止阶段 延迟一秒左右 将server进行关闭
+# 反向代理
+npm install http-proxy-middleware koa2-connect
 
-## 如何使用
+# API 文档
+npm install swagger-ui-dist
 
-```ts
+# 类型定义（TypeScript 项目）
+npm install -D @types/koa @types/koa__multer @types/koa-mount @types/koa-range @types/koa-static @types/koa2-cors
+```
+
+## 快速开始
+
+### 1. 创建应用入口
+
+```typescript
 import { FastCarApplication } from "@fastcar/core";
 import { Application } from "@fastcar/core/annotation";
-import { EnableKoa } from "@fastcar/koa/annotation";
-
-@Application //注入基础框架
-@EnableKoa //开启koa
-class APP {
- app!: FastCarApplication;
+import { EnableKoa, KoaMiddleware } from "@fastcar/koa/annotation";
+import { ExceptionGlobalHandler, KoaBodyParser } from "@fastcar/koa";
+
+@Application
+@EnableKoa
+@KoaMiddleware(ExceptionGlobalHandler, KoaBodyParser)
+class App {
+  app!: FastCarApplication;
 }
 
-export const app = new APP();
+export const app = new App();
 ```
 
-## 添加一个路由访问
+### 2. 创建控制器
 
-```ts
+```typescript
 import { Controller } from "@fastcar/core/annotation";
-import { GET } from "@fastcar/koa/annotation";
+import { GET, POST, RequestMapping } from "@fastcar/koa/annotation";
 import { Context } from "koa";
 
-
 @Controller
-export default class HelloController {
-
- @GET("/")
- home(params: string, ctx: Context) {
-  console.log("这边请注意 params是params和body二合一的参数 重名的值会优先取body的");
-  console.log('body取 ctx.request.body');
-  console.log('路径后参数取ctx.params');
-  return "hello world";
- }
+@RequestMapping("/api") // 基础路径前缀
+export default class UserController {
+  
+  @GET("/users")
+  async listUsers() {
+    return { code: 200, data: [] };
+  }
+
+  @POST("/users")
+  async createUser(data: any, ctx: Context) {
+    // data 自动合并了 query、body 和 params
+    return { code: 200, data: { id: 1, ...data } };
+  }
+
+  @GET("/users/:id")
+  async getUser(data: { id: string }, ctx: Context) {
+    // URL 参数在 ctx.params 中
+    const userId = ctx.params.id;
+    return { code: 200, data: { id: userId } };
+  }
+
+  @HEAD("/users/:id")
+  async checkUserExists(data: { id: string }, ctx: Context) {
+    // HEAD 请求通常用于检查资源是否存在，不返回响应体
+    const userId = ctx.params.id;
+    const exists = await checkUser(userId); // 假设的检查方法
+    ctx.status = exists ? 200 : 404;
+  }
 }
 ```
 
-## 如何引用koa中间件
+### 3. 配置文件 (application.yaml)
+
+```yaml
+koa:
+  server:
+    port: 3000
+    hostname: "0.0.0.0"
+  koaStatic:
+    "/static": "./resource/static"  # 路径别名映射
+  koaBodyOptions:
+    multipart: true
+    formidable:
+      maxFileSize: 200 * 1024 * 1024  # 200MB
+```
 
-```ts
-//自定义中间件
-//默认会出传入 app: FastCarApplication 可供选择
-function Example(): koa.Middleware {
-    return async (ctx: koa.Context, next: Function) => {
-        console.log("example--- in");
-        await next();
-        console.log("example--- out");
+## 配置
+
+### KoaConfig 类型
+
+```typescript
+type KoaConfig = {
+  // 服务器配置，支持多端口监听
+  server: ServerConfig | ServerConfig[];
+  
+  // 静态文件路径映射 { 访问路径: 文件系统路径 }
+  koaStatic?: { [key: string]: string };
+  
+  // koa-body 配置（文件上传）
+  koaBodyOptions?: { [key: string]: any };
+  
+  // @koa/bodyparser 配置
+  koaBodyParser?: { [key: string]: any };
+  
+  // 反向代理配置
+  koaProxy?: {
+    [path: string]: {
+      target: string;
+      changeOrigin?: boolean;
+      pathRewrite?: { [pattern: string]: string };
+      ws?: boolean;
     };
-}
+  };
+  
+  // 其他扩展配置
+  extra?: { [key: string]: any };
+};
+```
+
+## 装饰器/API 参考
+
+### 应用级装饰器
+
+| 装饰器 | 用途 | 参数 |
+|--------|------|------|
+| `@EnableKoa` | 启用 Koa 组件 | 无 |
+| `@KoaMiddleware(...middlewares)` | 注册中间件 | `...MiddleWareType[]` - 中间件函数数组，越靠前优先级越高 |
+
+### 路由装饰器
+
+| 装饰器 | HTTP 方法 | 简写别名 | 参数 |
+|--------|-----------|----------|------|
+| `@GetMapping(path)` | GET | `@GET` | `string` - 路由路径 |
+| `@PostMapping(path)` | POST | `@POST` | `string` - 路由路径 |
+| `@PutMapping(path)` | PUT | `@PUT` | `string` - 路由路径 |
+| `@DeleteMapping(path)` | DELETE | `@DELETE` | `string` - 路由路径 |
+| `@PatchMapping(path)` | PATCH | `@PATCH` | `string` - 路由路径 |
+| `@HeadMapping(path)` | HEAD | `@HEAD` | `string` - 路由路径 |
+| `@AllMapping(path)` | ALL | `@ALL` | `string` - 路由路径 |
+| `@RequestMapping(path)` | - | `@REQUEST` | `string` - 基础路径前缀 |
+
+### 控制器装饰器
+
+| 装饰器 | 用途 |
+|--------|------|
+| `@Controller` | 标记类为控制器，自动扫描路由 |
+
+### 路由方法参数
+
+控制器方法的参数约定：
+
+```typescript
+methodName(data: any, ctx: Context): any
+```
+
+- `data`: 自动合并 `query` + `body` + `params` 的对象（重名时 body 优先级最高）
+- `ctx`: Koa 的 Context 对象，可访问 `ctx.params`, `ctx.request.body`, `ctx.query` 等
+- 返回值: 自动设置为 `ctx.body`
+
+## 内置中间件
+
+### 1. ExceptionGlobalHandler
+
+全局异常捕获，统一处理控制器抛出的错误。
+
+```typescript
+import { ExceptionGlobalHandler } from "@fastcar/koa";
+
+@KoaMiddleware(ExceptionGlobalHandler)
+```
+
+### 2. KoaBodyParser
+
+请求体解析（推荐），支持 JSON、表单等。
+
+```typescript
+import { KoaBodyParser } from "@fastcar/koa";
+
+@KoaMiddleware(KoaBodyParser)
+// 配合配置
+// koaBodyParser:
+//   jsonLimit: "1mb"
+```
+
+### 3. KoaBody
+
+文件上传解析（基于 koa-body）。
+
+```typescript
+import { KoaBody } from "@fastcar/koa";
+
+@KoaMiddleware(KoaBody)
+// 配合配置
+// koaBodyOptions:
+//   multipart: true
+```
+
+### 4. KoaCors
+
+跨域支持。
 
-//在主入口内添加
+```typescript
+import { KoaCors } from "@fastcar/koa";
+
+@KoaMiddleware(KoaCors)
+```
+
+### 5. KoaStatic
+
+静态文件服务（整合 koa-static + koa-range + koa-mount）。
+
+```typescript
+import { KoaStatic } from "@fastcar/koa";
+
+@KoaMiddleware(KoaStatic)
+// 配合配置
+// koaStatic:
+//   "/": "./resource/public"
+//   "/uploads": "./uploads"
+```
+
+### 6. KoaMulter
+
+增强的文件上传解析（基于 @koa/multer）。
+
+```typescript
+import { KoaMulter } from "@fastcar/koa";
+
+@KoaMiddleware(KoaMulter)
+```
+
+### 7. KoaProxy
+
+反向代理（基于 http-proxy-middleware）。
+
+```typescript
+import { KoaProxy } from "@fastcar/koa";
+
+@KoaMiddleware(KoaProxy)
+// 配合配置
+// koaProxy:
+//   "/api":
+//     target: "http://backend-server:8080"
+//     changeOrigin: true
+```
+
+### 8. Swagger
+
+API 文档服务（需安装 swagger-ui-dist）。
+
+```typescript
+import { Swagger } from "@fastcar/koa";
+
+@KoaMiddleware(Swagger)
+// 访问 /swagger 查看文档
+```
+
+### 9. HeaderCoding
+
+Header 编码校验。
+
+```typescript
+import { HeaderCoding } from "@fastcar/koa";
+
+@KoaMiddleware(HeaderCoding)
+```
+
+## 示例
+
+### 自定义中间件
+
+```typescript
+import * as Koa from "koa";
 import { FastCarApplication } from "@fastcar/core";
-import { Application } from "@fastcar/core/annotation";
-import { EnableKoa } from "@fastcar/koa/annotation";
+import { KoaMiddleware } from "@fastcar/koa/annotation";
+
+// 中间件工厂函数，接收 FastCarApplication 实例
+function LoggerMiddleware(app: FastCarApplication): Koa.Middleware {
+  return async (ctx: Koa.Context, next: Function) => {
+    const start = Date.now();
+    console.log(`--> ${ctx.method} ${ctx.url}`);
+    
+    await next();
+    
+    const duration = Date.now() - start;
+    console.log(`<-- ${ctx.method} ${ctx.url} ${ctx.status} ${duration}ms`);
+  };
+}
 
-@Application //注入基础框架
-@EnableKoa //开启koa
-@KoaMiddleware(Example)
-class APP {
- app!: FastCarApplication;
+@Application
+@EnableKoa
+@KoaMiddleware(LoggerMiddleware, ExceptionGlobalHandler, KoaBodyParser)
+class App {
+  app!: FastCarApplication;
 }
+```
+
+### 多 HTTP 方法绑定
+
+```typescript
+import { Controller } from "@fastcar/core/annotation";
+import { GetMapping, PostMapping } from "@fastcar/koa/annotation";
+
+@Controller
+export default class ResourceController {
+  
+  // 同一个方法支持多种 HTTP 方法
+  @GetMapping("/resource")
+  @PostMapping("/resource")
+  handleResource(data: any) {
+    return { method: 'GET or POST', data };
+  }
+}
+```
 
-export const app = new APP();
+### 文件上传
+
+```typescript
+import { Controller } from "@fastcar/core/annotation";
+import { POST } from "@fastcar/koa/annotation";
+import { Context } from "koa";
+
+@Controller
+export default class UploadController {
+  
+  @POST("/upload")
+  async uploadFile(data: any, ctx: Context) {
+    // 文件信息在 ctx.request.files 中
+    const files = ctx.request.files;
+    return { 
+      code: 200, 
+      message: "上传成功",
+      files: Object.keys(files || {})
+    };
+  }
+}
 ```
 
-## 默认整合的koa中间件(开启方式为@KoaMiddleware(XX))
+## 类型定义
 
-* ExceptionGlobalHandler 用于koa运行时的异常情况捕捉
-* KoaBody 用于文件上传 与 koa-body的用法一致
-* KoaBodyParser 用于请求数据的解析 推荐客户端使用application/json的方式
-* KoaCors 跨域设置(后期可能会用更好的插件替代)
-* KoaStatic 整合了koa-static,koa-range,koa-mount用于静态文件访问,可设置别名
-* Swagger 用于展示api文档使用(后期支持自动化配置说明)
+### 导出路径
 
-## 注解说明
+```typescript
+// 主模块
+import { KoaApplication, KoaConfig } from "@fastcar/koa";
 
-* EnableKoa 作用于应用 开启Koa组件
+// 装饰器
+import { EnableKoa, KoaMiddleware, GET, POST, HEAD, ... } from "@fastcar/koa/annotation";
+```
 
-* AllMapping,ALL 作用于controller层 支持GET POST等请求方式访问
+### KoaApplication 类
 
-* GetMapping GET
+```typescript
+class KoaApplication {
+  public koaApp: Koa;  // Koa 实例
+  
+  start(): void;       // 启动服务
+  stop(): Promise<void>;  // 停止服务
+}
+```
 
-* PostMapping POST
+### 中间件类型
 
-* DeleteMapping DELETE
+```typescript
+type MiddleWareType = (
+  app: FastCarApplication, 
+  koaApp?: Koa
+) => Koa.Middleware | Koa.Middleware[] | Promise<Koa.Middleware | Koa.Middleware[]>;
+```
 
-* PatchMapping PATCH
+## 依赖关系
 
-* PutMapping PUT
+```
+@fastcar/koa
+├── @fastcar/core (peer)    - IoC 容器和组件生命周期
+├── @fastcar/server (peer)  - HTTP 服务器管理
+├── koa (^3.1.1)            - Web 框架
+└── @koa/router (^15.1.1)   - 路由
+```
 
-* RequestMapping REQUEST 作用于头部，用于追加url
+## 生命周期
 
-* KoaMiddleware 作用于应用 用于加载中间件 越在应用上面 优先级越高
+1. **启动阶段**（按优先级）：
+   - 加载自定义中间件（按 `@KoaMiddleware` 声明顺序）
+   - 加载路由（扫描所有 `@Controller` 类）
+   - 启动 HTTP 服务监听
 
-## 更多用法
+2. **停止阶段**：
+   - 延迟约 1 秒后关闭 server 连接
 
-参考项目git地址 @fastcar/koa/test下的simple内
+## 许可证
 
-## 项目开源地址
+MIT License
 
-* 项目下载 git clone <https://github.com/williamDazhangyu/fast-car.git>
+---
 
-* 在线查看 <https://github.com/williamDazhangyu/fast-car>
+**项目地址**: [https://github.com/williamDazhangyu/fast-car](https://github.com/williamDazhangyu/fast-car)

package/annotation.d.ts

@@ -25,6 +25,8 @@ export function PatchMapping(url?: string): MRet;
 
 export function PutMapping(url?: string): MRet;
 
+export function HeadMapping(url?: string): MRet;
+
 export function RequestMapping(url: string): Ret;
 
 export function ALL(url?: string): MRet;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fastcar/koa",
-	"version": "0.1.21",
+	"version": "0.1.23",
 	"homepage": "https://github.com/williamDazhangyu/fast-car",
 	"description": "fastcar框架下对koa的包装",
 	"main": "target/index.js",

package/src/annotation/router/HeadMapping.ts

@@ -0,0 +1,12 @@
+import { RouteMethods } from "../../type/RouteMethods";
+import AddMapping from "./AddMapping";
+
+export default function HeadMapping(url?: string) {
+	return function (target: any, name: string, descriptor: PropertyDescriptor) {
+		AddMapping(target, {
+			url,
+			method: name,
+			request: [RouteMethods.HeadMapping],
+		});
+	};
+}

package/src/annotation.ts

@@ -5,6 +5,7 @@ import AddMapping from "./annotation/router/AddMapping";
 import AllMapping from "./annotation/router/AllMapping";
 import DeleteMapping from "./annotation/router/DeleteMapping";
 import GetMapping from "./annotation/router/GetMapping";
+import HeadMapping from "./annotation/router/HeadMapping";
 import PatchMapping from "./annotation/router/PatchMapping";
 import PostMapping from "./annotation/router/PostMapping";
 import PutMapping from "./annotation/router/PutMapping";
@@ -18,6 +19,7 @@ const PUT = PutMapping;
 const PATCH = PatchMapping;
 const ALL = AllMapping;
 const REQUEST = RequestMapping;
+const HEAD = HeadMapping;
 
 export {
 	//关于请求方式注解
@@ -29,6 +31,7 @@ export {
 	PostMapping,
 	PutMapping,
 	RequestMapping,
+	HeadMapping,
 	//开启koa应用
 	EnableKoa,
 	//追加koa中间件
@@ -42,4 +45,5 @@ export {
 	ALL,
 	REQUEST,
 	KoaApp,
+	HEAD,
 };

package/src/type/RouteMethods.ts

@@ -5,4 +5,5 @@ export enum RouteMethods {
 	DeleteMapping = "delete",
 	PatchMapping = "patch",
 	AllMapping = "all",
+	HeadMapping = "head",
 }

package/target/annotation/router/HeadMapping.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = HeadMapping;
+const RouteMethods_1 = require("../../type/RouteMethods");
+const AddMapping_1 = require("./AddMapping");
+function HeadMapping(url) {
+    return function (target, name, descriptor) {
+        (0, AddMapping_1.default)(target, {
+            url,
+            method: name,
+            request: [RouteMethods_1.RouteMethods.HeadMapping],
+        });
+    };
+}

package/target/annotation.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoaApp = exports.REQUEST = exports.ALL = exports.PATCH = exports.PUT = exports.DELETE = exports.POST = exports.GET = exports.KoaMiddleware = exports.EnableKoa = exports.RequestMapping = exports.PutMapping = exports.PostMapping = exports.PatchMapping = exports.GetMapping = exports.DeleteMapping = exports.AllMapping = exports.AddMapping = void 0;
+exports.HEAD = exports.KoaApp = exports.REQUEST = exports.ALL = exports.PATCH = exports.PUT = exports.DELETE = exports.POST = exports.GET = exports.KoaMiddleware = exports.EnableKoa = exports.HeadMapping = exports.RequestMapping = exports.PutMapping = exports.PostMapping = exports.PatchMapping = exports.GetMapping = exports.DeleteMapping = exports.AllMapping = exports.AddMapping = void 0;
 const EnableKoa_1 = require("./annotation/EnableKoa");
 exports.EnableKoa = EnableKoa_1.default;
 const KoaApp_1 = require("./annotation/KoaApp");
@@ -15,6 +15,8 @@ const DeleteMapping_1 = require("./annotation/router/DeleteMapping");
 exports.DeleteMapping = DeleteMapping_1.default;
 const GetMapping_1 = require("./annotation/router/GetMapping");
 exports.GetMapping = GetMapping_1.default;
+const HeadMapping_1 = require("./annotation/router/HeadMapping");
+exports.HeadMapping = HeadMapping_1.default;
 const PatchMapping_1 = require("./annotation/router/PatchMapping");
 exports.PatchMapping = PatchMapping_1.default;
 const PostMapping_1 = require("./annotation/router/PostMapping");
@@ -38,3 +40,5 @@ const ALL = AllMapping_1.default;
 exports.ALL = ALL;
 const REQUEST = RequestMapping_1.default;
 exports.REQUEST = REQUEST;
+const HEAD = HeadMapping_1.default;
+exports.HEAD = HEAD;

package/target/type/RouteMethods.js

@@ -9,4 +9,5 @@ var RouteMethods;
     RouteMethods["DeleteMapping"] = "delete";
     RouteMethods["PatchMapping"] = "patch";
     RouteMethods["AllMapping"] = "all";
+    RouteMethods["HeadMapping"] = "head";
 })(RouteMethods || (exports.RouteMethods = RouteMethods = {}));