@fastcar/koa 0.1.20 → 0.1.22

package/README.md

@@ -1,115 +1,444 @@
-# 基于封装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 } };
+  }
 }
 ```
 
-## 如何引用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` - 路由路径 |
+| `@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, ... } 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fastcar/koa",
-	"version": "0.1.20",
+	"version": "0.1.22",
 	"homepage": "https://github.com/williamDazhangyu/fast-car",
 	"description": "fastcar框架下对koa的包装",
 	"main": "target/index.js",
@@ -33,33 +33,33 @@
 		"@fastcar/core": "^0.3.10",
 		"@fastcar/server": "^0.0.3",
 		"@types/co-body": "^6.1.3",
-		"@types/koa": "^2.13.5",
+		"@types/koa": "^3.0.1",
 		"@types/koa__multer": "*",
-		"@types/koa__router": "^12.0.4",
+		"koa2-cors": "^2.0.6",
 		"reflect-metadata": "*"
 	},
 	"dependencies": {
-		"@koa/bodyparser": "^5.1.1",
-		"@koa/router": "^13.1.0",
-		"koa": "^2.15.3"
+		"@koa/bodyparser": "^6.0.0",
+		"@koa/router": "^15.1.1",
+		"koa": "^3.1.1"
 	},
 	"peerDependencies": {
 		"@fastcar/core": "*",
 		"@fastcar/server": "*",
-		"@koa/multer": "^3.0.2",
-		"@types/koa-mount": "^4.0.1",
-		"@types/koa-range": "^0.3.2",
-		"@types/koa-static": "^4.0.2",
-		"@types/koa2-cors": "^2.0.2",
-		"http-proxy-middleware": "^3.0.5",
-		"koa-body": "^4.2.0",
-		"koa-mount": "^4.0.0",
-		"koa-range": "^0.3.0",
-		"koa-static": "^5.0.0",
-		"koa2-connect": "^1.0.2",
-		"koa2-cors": "^2.0.6",
+		"@koa/multer": "*",
+		"@types/koa-mount": "*",
+		"@types/koa-range": "*",
+		"@types/koa-static": "*",
+		"@types/koa2-cors": "*",
+		"http-proxy-middleware": "*",
+		"koa-body": "*",
+		"koa-mount": "*",
+		"koa-range": "*",
+		"koa-static": "*",
+		"koa2-connect": "*",
+		"koa2-cors": "*",
 		"multer": "*",
-		"path-to-regexp": "^8.3.0"
+		"path-to-regexp": "*"
 	},
 	"peerDependenciesMeta": {
 		"@types/koa-mount": {
@@ -106,6 +106,15 @@
 		},
 		"@koa/bodyparser": {
 			"optional": true
+		},
+		"http-proxy-middleware": {
+			"optional": true
+		},
+		"koa2-connect": {
+			"optional": true
+		},
+		"path-to-regexp": {
+			"optional": true
 		}
 	},
 	"repository": {

package/src/KoaApplication.ts

@@ -2,7 +2,7 @@ import "reflect-metadata";
 import { ApplicationStart, ApplicationStop, Autowired, Log } from "@fastcar/core/annotation";
 import { FastCarApplication, BootPriority, ComponentKind, Logger } from "@fastcar/core";
 import * as Koa from "koa";
-import * as KoaRouter from "@koa/router";
+import KoaRouter from "@koa/router";
 import { MethodType } from "./type/MethodType";
 import { DesignMeta } from "./type/DesignMeta";
 import { TypeUtil, ValidationUtil } from "@fastcar/core/utils";
@@ -53,7 +53,7 @@ export default class KoaApplication {
 	 *
 	 */
 	protected loadRoute(): Koa.Middleware {
-		let router = new KoaRouter();
+		const router = new KoaRouter();
 
 		let instanceList = this.app.getComponentByType(ComponentKind.Controller);
 

package/target/KoaApplication.js

@@ -13,7 +13,7 @@ require("reflect-metadata");
 const annotation_1 = require("@fastcar/core/annotation");
 const core_1 = require("@fastcar/core");
 const Koa = require("koa");
-const KoaRouter = require("@koa/router");
+const router_1 = require("@koa/router");
 const DesignMeta_1 = require("./type/DesignMeta");
 const utils_1 = require("@fastcar/core/utils");
 const server_1 = require("@fastcar/server");
@@ -52,7 +52,7 @@ let KoaApplication = class KoaApplication {
      *
      */
     loadRoute() {
-        let router = new KoaRouter();
+        const router = new router_1.default();
         let instanceList = this.app.getComponentByType(core_1.ComponentKind.Controller);
         //查找绑定的url
         instanceList.forEach((instance) => {

package/test/logs/sys.log

@@ -183,3 +183,26 @@
 {"timestamp":"2025-12-23 10:59:33.833","level":"INFO","label":"sys","message":"http server is running in 1234"}
 {"timestamp":"2025-12-23 10:59:33.834","level":"INFO","label":"sys","message":"start server koaSimple is run"}
 {"timestamp":"2025-12-23 10:59:33.835","level":"INFO","label":"sys","message":"version 1.0.0"}
+{"timestamp":"2025-12-23 22:14:30.131","level":"INFO","label":"sys","message":"Start scanning component"}
+{"timestamp":"2025-12-23 22:14:33.982","level":"INFO","label":"sys","message":"Complete component scan"}
+{"timestamp":"2025-12-23 22:14:33.984","level":"INFO","label":"sys","message":"Call application initialization method"}
+{"timestamp":"2025-12-23 22:14:34.06","level":"INFO","label":"sys","message":"http server is running in 1234"}
+{"timestamp":"2025-12-23 22:14:34.07","level":"INFO","label":"sys","message":"start server koaSimple is run"}
+{"timestamp":"2025-12-23 22:14:34.09","level":"INFO","label":"sys","message":"version 1.0.0"}
+{"timestamp":"2025-12-23 22:29:19.999","level":"INFO","label":"sys","message":"Start scanning component"}
+{"timestamp":"2025-12-23 22:29:20.679","level":"INFO","label":"sys","message":"Complete component scan"}
+{"timestamp":"2025-12-23 22:29:20.681","level":"INFO","label":"sys","message":"Call application initialization method"}
+{"timestamp":"2025-12-23 22:29:20.692","level":"INFO","label":"sys","message":"http server is running in 1234"}
+{"timestamp":"2025-12-23 22:29:20.693","level":"INFO","label":"sys","message":"start server koaSimple is run"}
+{"timestamp":"2025-12-23 22:29:20.694","level":"INFO","label":"sys","message":"version 1.0.0"}
+{"timestamp":"2025-12-24 16:51:54.144","level":"INFO","label":"sys","message":"Start scanning component"}
+{"timestamp":"2025-12-24 16:51:55.401","level":"INFO","label":"sys","message":"Complete component scan"}
+{"timestamp":"2025-12-24 16:51:55.401","level":"INFO","label":"sys","message":"Call application initialization method"}
+{"timestamp":"2025-12-24 16:51:55.404","level":"ERROR","label":"sys","message":"Unhandled Rejection at:","splat":"[{}]"}
+{"timestamp":"2025-12-24 16:51:55.408","level":"ERROR","label":"sys","message":"reason: Cannot find module 'koa2-cors'\nRequire stack:\n- D:\\code\\fast-car\\fastcar-koa\\src\\middleware\\KoaCors.ts\n- D:\\code\\fast-car\\fastcar-koa\\test\\simple\\app.ts","splat":"[{\"code\":\"MODULE_NOT_FOUND\",\"requireStack\":[\"D:\\\\code\\\\fast-car\\\\fastcar-koa\\\\src\\\\middleware\\\\KoaCors.ts\",\"D:\\\\code\\\\fast-car\\\\fastcar-koa\\\\test\\\\simple\\\\app.ts\"]}]","stack":"Error: Cannot find module 'koa2-cors'\nRequire stack:\n- D:\\code\\fast-car\\fastcar-koa\\src\\middleware\\KoaCors.ts\n- D:\\code\\fast-car\\fastcar-koa\\test\\simple\\app.ts\n    at Function.<anonymous> (node:internal/modules/cjs/loader:1401:15)\n    at Function.Module._resolveFilename.sharedData.moduleResolveFilenameHook.installedValue [as _resolveFilename] (D:\\code\\fast-car\\node_modules\\@cspotcode\\source-map-support\\source-map-support.js:811:30)\n    at defaultResolveImpl (node:internal/modules/cjs/loader:1057:19)\n    at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1062:22)\n    at Function._load (node:internal/modules/cjs/loader:1211:37)\n    at TracingChannel.traceSync (node:diagnostics_channel:322:14)\n    at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)\n    at Module.require (node:internal/modules/cjs/loader:1487:12)\n    at require (node:internal/modules/helpers:135:16)\n    at KoaApplication.KoaCors (D:\\code\\fast-car\\fastcar-koa\\src\\middleware\\KoaCors.ts:6:19)"}
+{"timestamp":"2025-12-24 16:52:22.882","level":"INFO","label":"sys","message":"Start scanning component"}
+{"timestamp":"2025-12-24 16:52:23.412","level":"INFO","label":"sys","message":"Complete component scan"}
+{"timestamp":"2025-12-24 16:52:23.413","level":"INFO","label":"sys","message":"Call application initialization method"}
+{"timestamp":"2025-12-24 16:52:49.516","level":"INFO","label":"sys","message":"http server is running in 1234"}
+{"timestamp":"2025-12-24 16:52:49.517","level":"INFO","label":"sys","message":"start server koaSimple is run"}
+{"timestamp":"2025-12-24 16:52:49.518","level":"INFO","label":"sys","message":"version 1.0.0"}