@fastcar/koa 0.1.9

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2021-2022 william_zhong
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# 基于封装koa的web成型框架
+
+## 快速安装
+
+npm install fastcar@koa
+
+## 基本原理
+
+* 采用@fastcar/core框架，然后将koa包装成一个基础组件进行调用
+* 加载顺序为优先加载自定义中间件->加载自定义路由->启动http服务进行监听
+* 停止阶段 延迟一秒左右 将server进行关闭
+
+## 如何使用
+
+```ts
+import { FastCarApplication } from "@fastcar/core";
+import { Application } from "@fastcar/core/annotation";
+import { EnableKoa } from "@fastcar/koa/annotation";
+
+@Application //注入基础框架
+@EnableKoa //开启koa
+class APP {
+ app!: FastCarApplication;
+}
+
+export const app = new APP();
+```
+
+## 添加一个路由访问
+
+```ts
+import { Controller } from "@fastcar/core/annotation";
+import { GET } from "@fastcar/koa/annotation";
+
+@Controller
+export default class HelloController {
+
+ @GET("/")
+ home() {
+  return "hello world";
+ }
+}
+```
+
+## 如何引用koa中间件
+
+```ts
+//自定义中间件
+//默认会出传入 app: FastCarApplication 可供选择
+function Example(): koa.Middleware {
+    return async (ctx: koa.Context, next: Function) => {
+        console.log("example--- in");
+        await next();
+        console.log("example--- out");
+    };
+}
+
+//在主入口内添加
+import { FastCarApplication } from "@fastcar/core";
+import { Application } from "@fastcar/core/annotation";
+import { EnableKoa } from "@fastcar/koa/annotation";
+
+@Application //注入基础框架
+@EnableKoa //开启koa
+@KoaMiddleware(Example)
+class APP {
+ app!: FastCarApplication;
+}
+
+export const app = new APP();
+```
+
+## 默认整合的koa中间件(开启方式为@KoaMiddleware(XX))
+
+* ExceptionGlobalHandler 用于koa运行时的异常情况捕捉
+* KoaBody 用于文件上传 与 koa-body的用法一致
+* KoaBodyParser 用于请求数据的解析 推荐客户端使用application/json的方式
+* KoaCors 跨域设置(后期可能会用更好的插件替代)
+* KoaStatic 整合了koa-static,koa-range,koa-mount用于静态文件访问,可设置别名
+* Swagger 用于展示api文档使用(后期支持自动化配置说明)
+
+## 注解说明
+
+* EnableKoa 作用于应用 开启Koa组件
+
+* AllMapping,ALL 作用于controller层 支持GET POST等请求方式访问
+
+* GetMapping GET
+
+* PostMapping POST
+
+* DeleteMapping DELETE
+
+* PatchMapping PATCH
+
+* PutMapping PUT
+
+* RequestMapping REQUEST 作用于头部，用于追加url
+
+* KoaMiddleware 作用于应用 用于加载中间件 越在应用上面 优先级越高
+
+## 更多用法
+
+参考项目git地址 @fastcar/koa/test下的simple内
+
+## 项目开源地址
+
+* 项目下载 git clone <https://github.com/williamDazhangyu/fast-car.git>
+
+* 在线查看 <https://github.com/williamDazhangyu/fast-car>

package/annotation.d.ts

@@ -0,0 +1,46 @@
+import { MethodType } from "./src/type/MethodType";
+
+import * as Koa from "koa";
+
+type Ret = (target: any) => void;
+
+type MRet = (target: any, name: string, descriptor: PropertyDescriptor) => void;
+
+type MiddleWareType = (...args: any) => Koa.Middleware | Koa.Middleware[];
+
+//关于请求方式注解
+export function AddMapping(target: any, info: MethodType): void;
+
+export function AllMapping(url?: string): MRet;
+
+export function DeleteMapping(url?: string): MRet;
+
+export function GetMapping(url?: string): MRet;
+
+export function PostMapping(url?: string): MRet;
+
+export function PatchMapping(url?: string): MRet;
+
+export function PutMapping(url?: string): MRet;
+
+export function RequestMapping(url: string): Ret;
+
+export function ALL(url?: string): MRet;
+
+export function DELETE(url?: string): MRet;
+
+export function GET(url?: string): MRet;
+
+export function POST(url?: string): MRet;
+
+export function PATCH(url?: string): MRet;
+
+export function PUT(url?: string): MRet;
+
+export function REQUEST(url?: string): Ret;
+
+//开启koa应用
+export function EnableKoa(target: any): void;
+
+//中间件添加拓展
+export function KoaMiddleware(...args: MiddleWareType[]): Ret;

package/index.d.ts

@@ -0,0 +1,63 @@
+import { FastCarApplication, Logger } from "@fastcar/core";
+import * as Koa from "koa";
+import * as koaBody from "koa-body";
+import * as bodyParser from "koa-bodyparser";
+import { ServerConfig } from "@fastcar/server";
+
+type MiddleWareType = (...args: any) => Koa.Middleware | Koa.Middleware[];
+
+export class KoaApplication {
+	protected app: FastCarApplication;
+	protected sysLogger: Logger;
+	protected koaApp: Koa;
+
+	/***
+	 * @version 1.0 加载中间件
+	 *
+	 */
+	protected loadMiddleWare(list: Koa.Middleware | Koa.Middleware[]): void;
+
+	/***
+	 * @version 1.0 加载路由
+	 *
+	 */
+	protected loadRoute(): Koa.Middleware;
+
+	/***
+	 * @version 1.0 应用启动时加载应用 加载顺序为中间件->路由->开启服务
+	 */
+	start(): void;
+
+	/***
+	 * @version 1.0 应用停止时加载 依次关闭http服务器
+	 */
+	stop(): void;
+}
+
+export type KoaConfig = {
+	server: ServerConfig[] | ServerConfig; //监听的端口号
+	koaStatic?: string[]; //相对路径为resource下的 或者绝对文件路径
+	koaBodyOptions?: koaBody.IKoaBodyOptions; //文件上传的解析
+	koaBodyParser?: bodyParser.Options; //解析请求
+	extra?: { [key: string]: any }; //拓展设置
+};
+
+//全局异常捕捉 可以用自定义的替换这个函数
+export function ExceptionGlobalHandler(app: FastCarApplication): MiddleWareType;
+
+//解析body参数
+export function KoaBody(app: FastCarApplication): MiddleWareType;
+
+//解析Body参数 这个更好用
+export function KoaBodyParser(app: FastCarApplication): MiddleWareType;
+
+//支持跨域
+export function KoaCors(app: FastCarApplication): MiddleWareType;
+
+//解析静态文件
+export function KoaStatic(app: FastCarApplication): MiddleWareType;
+
+//支持api说明
+export function Swagger(app: FastCarApplication): MiddleWareType;
+
+export * from "./src/type/DesignMeta";

package/package.json

@@ -0,0 +1,123 @@
+{
+	"name": "@fastcar/koa",
+	"version": "0.1.9",
+	"homepage": "https://github.com/williamDazhangyu/fast-car",
+	"description": "fastcar框架下对koa的包装",
+	"main": "target/index.js",
+	"author": "william_zhong",
+	"license": "MIT",
+	"types": "index.d.ts",
+	"exports": {
+		".": "./target/index.js",
+		"./annotation": "./target/annotation.js"
+	},
+	"files": [
+		"src",
+		"target",
+		"test",
+		"index.d.ts",
+		"annotation.d.ts",
+		"LICENSE"
+	],
+	"keywords": [
+		"koa",
+		"web",
+		"node",
+		"@fastcar/core",
+		"@fastcar/koa"
+	],
+	"engines": {
+		"node": ">=16"
+	},
+	"devDependencies": {
+		"@fastcar/core": "^0.2.38",
+		"@fastcar/server": "^0.0.3",
+		"@types/koa": "^2.13.5",
+		"reflect-metadata": "^0.1.13"
+	},
+	"dependencies": {
+		"@types/koa-bodyparser": "^4.3.3",
+		"@types/koa-mount": "^4.0.1",
+		"@types/koa-range": "^0.3.2",
+		"@types/koa-router": "^7.4.4",
+		"@types/koa-static": "^4.0.2",
+		"@types/koa2-cors": "^2.0.2",
+		"koa": "2.13.1",
+		"koa-body": "^4.2.0",
+		"koa-bodyparser": "^4.3.0",
+		"koa-mount": "^4.0.0",
+		"koa-range": "^0.3.0",
+		"koa-router": "^10.1.1",
+		"koa-static": "^5.0.0",
+		"koa2-cors": "^2.0.6"
+	},
+	"peerDependencies": {
+		"@fastcar/core": "*",
+		"@fastcar/server": "*",
+		"@types/koa-bodyparser": "^4.3.3",
+		"@types/koa-mount": "^4.0.1",
+		"@types/koa-range": "^0.3.2",
+		"@types/koa-router": "^7.4.4",
+		"@types/koa-static": "^4.0.2",
+		"@types/koa2-cors": "^2.0.2",
+		"koa-body": "^4.2.0",
+		"koa-bodyparser": "^4.3.0",
+		"koa-mount": "^4.0.0",
+		"koa-range": "^0.3.0",
+		"koa-router": "^10.1.1",
+		"koa-static": "^5.0.0",
+		"koa2-cors": "^2.0.6",
+		"swagger-ui-dist": "4.5.0"
+	},
+	"peerDependenciesMeta": {
+		"@types/koa-bodyparser": {
+			"optional": true
+		},
+		"@types/koa-mount": {
+			"optional": true
+		},
+		"@types/koa-range": {
+			"optional": true
+		},
+		"@types/koa-router": {
+			"optional": true
+		},
+		"@types/koa-static": {
+			"optional": true
+		},
+		"@types/koa2-cors": {
+			"optional": true
+		},
+		"koa-body": {
+			"optional": true
+		},
+		"koa-bodyparser": {
+			"optional": true
+		},
+		"koa-mount": {
+			"optional": true
+		},
+		"koa-range": {
+			"optional": true
+		},
+		"koa-router": {
+			"optional": true
+		},
+		"koa-static": {
+			"optional": true
+		},
+		"koa2-cors": {
+			"optional": true
+		},
+		"swagger-ui-dist": {
+			"optional": true
+		}
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/williamDazhangyu/fast-car.git"
+	},
+	"scripts": {
+		"build": "tsc"
+	}
+}

package/src/KoaApplication.ts

@@ -0,0 +1,139 @@
+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 { MethodType } from "./type/MethodType";
+import { DesignMeta } from "./type/DesignMeta";
+import { TypeUtil } from "@fastcar/core/utils";
+import { KoaConfig } from "./type/KoaConfig";
+import { ServerApplication } from "@fastcar/server";
+
+/***
+ * @version 1.0 koa基础组件启动
+ *
+ */
+@ApplicationStart(BootPriority.Lowest, "start")
+@ApplicationStop(BootPriority.Base, "stop")
+export default class KoaApplication {
+	@Autowired
+	protected app!: FastCarApplication;
+
+	@Log("koa")
+	protected koaLogger!: Logger;
+
+	protected koaApp: Koa;
+
+	@Autowired
+	private serverApplication!: ServerApplication;
+
+	constructor() {
+		this.koaApp = new Koa();
+	}
+
+	/***
+	 * @version 1.0 加载中间件
+	 *
+	 */
+	protected loadMiddleWare(list: Koa.Middleware | Koa.Middleware[]): void {
+		if (Array.isArray(list)) {
+			list.forEach((item) => {
+				if (TypeUtil.isFunction(item)) {
+					this.koaApp.use(item);
+				}
+			});
+		} else {
+			if (TypeUtil.isFunction(list)) {
+				this.koaApp.use(list);
+			}
+		}
+	}
+
+	/***
+	 * @version 1.0 加载路由
+	 *
+	 */
+	protected loadRoute(): Koa.Middleware {
+		let router: any = new KoaRouter();
+
+		let instanceList = this.app.getComponentByType(ComponentKind.Controller);
+
+		//查找绑定的url
+		instanceList.forEach((instance) => {
+			let routerMap: Map<string, MethodType> = Reflect.getMetadata(DesignMeta.ROUTER_MAP, instance);
+			//移除空的map结构
+			if (!routerMap || routerMap.size == 0) {
+				return;
+			}
+			routerMap.forEach((item) => {
+				//去除ctx的影响
+				let callBack = async (ctx: any, next?: Function) => {
+					//进行参数的取值
+					let body = Object.keys(ctx.query).length > 0 ? ctx.query : ctx.request.body;
+
+					if (!body) {
+						body = {};
+					}
+
+					if (!!ctx.params) {
+						Object.assign(body, ctx.params);
+					}
+
+					let res = await instance[item.method](body, ctx);
+					if (!!res) {
+						ctx.body = res;
+					}
+
+					if (next) {
+						await next();
+					}
+				};
+
+				for (let r of item.request) {
+					//进行绑定 加载router路由的执行方法
+					Reflect.apply(router[`${r}`], router, [item.url, callBack]);
+				}
+			});
+		});
+
+		return router.routes();
+	}
+
+	start(): void {
+		const koaApp = this.koaApp;
+
+		//加载中间件
+		let middlewareList: Function[] = this.app.getSetting(DesignMeta.KoaMIDDLEWARE);
+		if (Array.isArray(middlewareList)) {
+			for (let m of middlewareList) {
+				if (TypeUtil.isPromise(m)) {
+					Reflect.apply(m, this, [this.app, koaApp]).then((tmpList: Koa.Middleware | Koa.Middleware[]) => {
+						this.loadMiddleWare(tmpList);
+					});
+				} else {
+					let tmpList: Koa.Middleware | Koa.Middleware[] = Reflect.apply(m, this, [this.app, koaApp]);
+					this.loadMiddleWare(tmpList);
+				}
+			}
+		}
+
+		//加载路由
+		koaApp.use(this.loadRoute());
+
+		//读取配置文件 创建服务器
+		let appCallback = koaApp.callback();
+		let koaConfig: KoaConfig = this.app.getSetting("koa");
+
+		if (!!koaConfig.server) {
+			if (Array.isArray(koaConfig.server)) {
+				koaConfig.server.forEach((server) => {
+					this.serverApplication.createServer(server, appCallback);
+				});
+			} else {
+				this.serverApplication.createServer(koaConfig.server, appCallback);
+			}
+		}
+	}
+
+	async stop(): Promise<void> {}
+}

package/src/annotation/EnableKoa.ts

@@ -0,0 +1,9 @@
+import { ComponentInjection } from "@fastcar/core/annotation";
+import { EnableServer } from "@fastcar/server";
+
+//开启koa应用
+export default function EnableKoa(target: any) {
+	let fp = require.resolve("../KoaApplication");
+	ComponentInjection(target, fp);
+	EnableServer(target);
+}

package/src/annotation/KoaMiddleware.ts

@@ -0,0 +1,19 @@
+import "reflect-metadata";
+import { DesignMeta } from "../type/DesignMeta";
+import * as Koa from "koa";
+
+type MiddleWareType = (...args: any) => Koa.Middleware | Koa.Middleware[];
+
+//加载koa中间件
+export default function KoaMiddleware(...args: MiddleWareType[]) {
+	return function(target: any) {
+		let middlewareList: MiddleWareType[] = Reflect.get(target.prototype, DesignMeta.KoaMIDDLEWARE);
+		if (!middlewareList) {
+			middlewareList = args;
+		} else {
+			//由于注解方式是从下至上运行 和我们理解的书写习惯不一样，所以这边做了一个反序
+			middlewareList = [...args, ...middlewareList];
+		}
+		Reflect.set(target.prototype, DesignMeta.KoaMIDDLEWARE, middlewareList);
+	};
+}

package/src/annotation/router/AddMapping.ts

@@ -0,0 +1,31 @@
+import "reflect-metadata";
+import { MethodType } from "../../type/MethodType";
+import { DesignMeta } from "../../type/DesignMeta";
+
+export default function AddMapping(target: any, info: MethodType) {
+
+	if(!info.url) {
+		info.url = info.method;
+	}
+
+	//格式化url 以/开头
+	if (!info.url.startsWith("/")) {
+		info.url = "/" + info.url;
+	}
+
+	let routerMap: Map<string, MethodType> = Reflect.getMetadata(DesignMeta.ROUTER_MAP, target);
+	if (!routerMap) {
+		routerMap = new Map();
+		Reflect.defineMetadata(DesignMeta.ROUTER_MAP, routerMap, target);
+	}
+
+	let curr = routerMap.get(info.url);
+	if (!curr) {
+		routerMap.set(info.url, info);
+	} else {
+		if (info.url != curr.url) {
+			console.warn(`The two URL names are inconsisten in (${info.url},${curr.url})`);
+		}
+		curr.request = [...info.request, ...curr.request];
+	}
+}

package/src/annotation/router/AllMapping.ts

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

package/src/annotation/router/DeleteMapping.ts

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

package/src/annotation/router/GetMapping.ts

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

package/src/annotation/router/PatchMapping.ts

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

package/src/annotation/router/PostMapping.ts

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

package/src/annotation/router/PutMapping.ts

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

package/src/annotation/router/RequestMapping.ts

@@ -0,0 +1,23 @@
+import "reflect-metadata";
+import { MethodType } from "../../type/MethodType";
+import { DesignMeta } from "../../type/DesignMeta";
+import { FormatStr } from "@fastcar/core/utils";
+
+//加载值头部的url
+export default function RequestMapping(url?: string) {
+	return function (target: any) {
+		let tname = FormatStr.formatFirstToLow(target.name);
+		let headUrl = url || tname;
+
+		if (!headUrl.startsWith("/")) {
+			headUrl = "/" + headUrl;
+		}
+
+		let routerMap: Map<string, MethodType> = Reflect.getMetadata(DesignMeta.ROUTER_MAP, target.prototype);
+		if (!!routerMap) {
+			routerMap.forEach((item) => {
+				item.url = headUrl + item.url;
+			});
+		}
+	};
+}