@hile/http 1.0.6

package/README.md

@@ -0,0 +1,234 @@
+# @hile/http
+
+基于 Koa + find-my-way 的 HTTP 服务框架，支持中间件、路由注册和文件系统自动路由加载。
+
+## 安装
+
+```bash
+pnpm add @hile/http
+```
+
+## 快速开始
+
+```typescript
+import { Http } from '@hile/http'
+
+const http = new Http({ port: 3000 })
+
+http.get('/hello', async (ctx) => {
+  ctx.body = 'Hello, World!'
+})
+
+const close = await http.listen(() => {
+  console.log('Server running on http://localhost:3000')
+})
+```
+
+## 核心概念
+
+### 创建服务
+
+```typescript
+const http = new Http({
+  port: 3000,
+  keys: ['secret1', 'secret2'],  // 可选，不传则自动生成
+})
+```
+
+### 中间件
+
+通过 `use()` 注册全局中间件，支持链式调用。中间件必须在 `listen()` 之前注册。
+
+```typescript
+http
+  .use(async (ctx, next) => {
+    const start = Date.now()
+    await next()
+    ctx.set('X-Response-Time', `${Date.now() - start}ms`)
+  })
+  .use(async (ctx, next) => {
+    console.log(`${ctx.method} ${ctx.url}`)
+    await next()
+  })
+```
+
+### 路由
+
+使用快捷方法注册路由，支持路径参数和多个中间件：
+
+```typescript
+http.get('/users', async (ctx) => {
+  ctx.body = [{ id: 1, name: 'Alice' }]
+})
+
+http.get('/users/:id', async (ctx) => {
+  ctx.body = { id: ctx.params.id }
+})
+
+http.post('/users', authMiddleware, async (ctx) => {
+  ctx.body = { created: true }
+})
+```
+
+所有路由方法返回注销函数，调用后路由不再匹配：
+
+```typescript
+const off = http.get('/temporary', async (ctx) => {
+  ctx.body = 'gone soon'
+})
+
+off() // 移除该路由
+```
+
+支持的快捷方法：`get`、`post`、`put`、`delete`、`trace`，或使用 `route()` 指定任意 HTTP 方法：
+
+```typescript
+http.route('PATCH', '/users/:id', async (ctx) => {
+  ctx.body = { patched: true }
+})
+```
+
+### 启动与关闭
+
+```typescript
+const close = await http.listen((server) => {
+  console.log(`Listening on port ${http.port}`)
+})
+
+// 关闭服务
+close()
+```
+
+## 文件系统路由
+
+### 定义控制器
+
+使用 `defineController` 定义路由控制器。返回值自动赋给 `ctx.body`。
+
+```typescript
+// controllers/users/index.controller.ts
+import { defineController } from '@hile/http'
+
+export default defineController('GET', async (ctx) => {
+  return { users: [] }
+})
+```
+
+带中间件：
+
+```typescript
+import { defineController } from '@hile/http'
+
+const auth = async (ctx, next) => {
+  if (!ctx.headers.authorization) ctx.throw(401)
+  await next()
+}
+
+export default defineController('POST', [auth], async (ctx) => {
+  return { created: true }
+})
+```
+
+同一文件导出多个控制器：
+
+```typescript
+// controllers/users/[id].controller.ts
+import { defineController } from '@hile/http'
+
+const getUser = defineController('GET', async (ctx) => {
+  return { id: ctx.params.id }
+})
+
+const updateUser = defineController('PUT', [auth], async (ctx) => {
+  return { updated: true }
+})
+
+export default [getUser, updateUser]
+```
+
+### 加载路由
+
+使用 `load()` 自动扫描目录并注册路由：
+
+```typescript
+await http.load('./src/controllers', {
+  suffix: 'controller',    // 匹配 *.controller.{ts,js}
+  prefix: '/api',          // 路由前缀
+  defaultSuffix: '/index', // index 文件映射到父路径
+})
+```
+
+### 路径映射规则
+
+| 文件路径 | 路由路径 |
+|---------|---------|
+| `index.controller.ts` | `/api` |
+| `users/index.controller.ts` | `/api/users` |
+| `users/list.controller.ts` | `/api/users/list` |
+| `users/[id].controller.ts` | `/api/users/:id` |
+| `[category]/[id].controller.ts` | `/api/:category/:id` |
+
+路径中的 `[param]` 会自动转换为 `:param` 路由参数。
+
+## 与 hile 集成
+
+配合 `hile` 服务容器管理 HTTP 服务的生命周期：
+
+```typescript
+import { defineService } from 'hile'
+import { Http } from '@hile/http'
+
+export const httpService = defineService(async (shutdown) => {
+  const http = new Http({ port: 3000 })
+
+  await http.load('./src/controllers', {
+    suffix: 'controller',
+    prefix: '/api',
+  })
+
+  const close = await http.listen()
+  shutdown(close)
+
+  return http
+})
+```
+
+## API
+
+### Http
+
+| 方法 | 说明 |
+|------|------|
+| `new Http(props)` | 创建实例，`port` 必填 |
+| `port` | 获取端口号 |
+| `use(middleware)` | 注册全局中间件，返回 `this` |
+| `listen(onListen?)` | 启动服务，返回关闭函数 |
+| `get(url, ...mw)` | 注册 GET 路由，返回注销函数 |
+| `post(url, ...mw)` | 注册 POST 路由，返回注销函数 |
+| `put(url, ...mw)` | 注册 PUT 路由，返回注销函数 |
+| `delete(url, ...mw)` | 注册 DELETE 路由，返回注销函数 |
+| `trace(url, ...mw)` | 注册 TRACE 路由，返回注销函数 |
+| `route(method, url, ...mw)` | 注册任意方法路由，返回注销函数 |
+| `load(dir, options?)` | 加载文件系统路由，返回注销函数 |
+
+### defineController
+
+| 调用形式 | 说明 |
+|---------|------|
+| `defineController(method, fn)` | 无中间件 |
+| `defineController(method, [mw...], fn)` | 带中间件 |
+
+- 控制器函数接收 `ctx`，返回值非 `undefined` 时自动设为 `ctx.body`
+- 控制器文件必须 `export default` 导出
+
+### load 选项
+
+| 选项 | 默认值 | 说明 |
+|------|-------|------|
+| `suffix` | `'controller'` | 文件后缀标记 |
+| `prefix` | — | 路由前缀 |
+| `defaultSuffix` | `'/index'` | 映射到父路径的文件名 |
+
+## License
+
+MIT

package/dist/controller.d.ts

@@ -0,0 +1,17 @@
+import { HTTPMethod } from 'find-my-way';
+import { Context, Middleware } from 'koa';
+export type ControllerFunction<R> = (ctx: Context) => R | Promise<R>;
+export interface ControllerRegisterProps<R> {
+    id: number;
+    method: HTTPMethod;
+    middlewares: Middleware[];
+    data: Record<string, any>;
+}
+/**
+ * 定义路由控制器
+ * @param method 请求方法
+ * @param middlewares 中间件，可以是中间件数组或控制器函数
+ * @param fn 控制器函数
+ * @returns 路由控制器注册信息
+ */
+export declare function defineController<R>(method: HTTPMethod, middlewares: Middleware[] | ControllerFunction<R>, fn?: ControllerFunction<R>): ControllerRegisterProps<R>;

package/dist/controller.js

@@ -0,0 +1,37 @@
+let _id = 1;
+/**
+ * 定义路由控制器
+ * @param method 请求方法
+ * @param middlewares 中间件，可以是中间件数组或控制器函数
+ * @param fn 控制器函数
+ * @returns 路由控制器注册信息
+ */
+export function defineController(method, middlewares, fn) {
+    let _middlewares = [];
+    let _fn = undefined;
+    if (typeof middlewares === 'function' && !fn) {
+        _fn = middlewares;
+        _middlewares = [];
+    }
+    else {
+        _middlewares = middlewares;
+        _fn = fn;
+    }
+    if (!Array.isArray(_middlewares))
+        throw new Error('Middlewares must be an array');
+    if (!_fn)
+        throw new Error('Controller function is required');
+    const id = _id++;
+    _middlewares.push(async (ctx) => {
+        const result = await _fn(ctx);
+        if (result !== undefined) {
+            ctx.body = result;
+        }
+    });
+    return {
+        id,
+        method,
+        middlewares: _middlewares,
+        data: {},
+    };
+}

package/dist/find-my-way.d.ts

@@ -0,0 +1,11 @@
+import { Config, HTTPVersion, HTTPMethod } from 'find-my-way';
+import { Middleware } from 'koa';
+export { HTTPVersion, };
+export interface Instance {
+    on(method: HTTPMethod | HTTPMethod[], path: string, ...middlewares: Middleware[]): Instance;
+    off(method: HTTPMethod | HTTPMethod[], path: string): Instance;
+    prettyPrint(): string;
+    routes(): Middleware;
+}
+declare const _default: <V extends HTTPVersion = HTTPVersion.V1>(options: Config<V>) => Instance;
+export default _default;

package/dist/find-my-way.js

@@ -0,0 +1,47 @@
+import compose from 'koa-compose';
+import FindMyWay, { HTTPVersion } from 'find-my-way';
+import { METHODS } from 'node:http';
+export { HTTPVersion, };
+export default (options) => {
+    const fmw = FindMyWay(options);
+    const r = {};
+    function on(method, path, ...middlewares) {
+        // optional store argument
+        let store;
+        if (middlewares.length > 1 && typeof middlewares[middlewares.length - 1] === 'object') {
+            store = middlewares.pop();
+        }
+        // @ts-ignore
+        fmw.on(method, path, compose(middlewares), store);
+        return r;
+    }
+    r.on = on;
+    // @ts-ignore
+    r.all = (path, ...middlewares) => on(METHODS, path, ...middlewares);
+    METHODS.forEach((m) => {
+        // @ts-ignore
+        r[m.toLowerCase()] = (path, ...middlewares) => on(m, path, ...middlewares);
+    });
+    [
+        'off',
+        'reset',
+        'prettyPrint',
+        'find',
+    ].forEach((m) => {
+        // @ts-ignore
+        r[m] = fmw[m].bind(fmw);
+    });
+    r.routes = () => (ctx, next) => {
+        // @ts-ignore
+        const handle = fmw.find(ctx.method, ctx.path);
+        if (!handle) {
+            // @ts-ignore
+            return fmw.defaultRoute && fmw.defaultRoute(ctx, next);
+        }
+        ctx.params = handle.params;
+        ctx.store = handle.store;
+        // @ts-ignore
+        return handle.handler(ctx, next);
+    };
+    return r;
+};

package/dist/http.d.ts

@@ -0,0 +1,109 @@
+import { Middleware } from 'koa';
+import { Config, HTTPMethod, HTTPVersion } from 'find-my-way';
+import { Server } from 'node:http';
+import { LoaderFromOptions } from './loader';
+export type HttpProps = {
+    port: number;
+    keys?: string[];
+} & Omit<Config<HTTPVersion.V1>, 'defaultRoute'>;
+/**
+ * Http 服务类
+ * @description - 提供 HTTP 服务的基本功能
+ * @example
+ * const http = new Http({
+ *   port: 3000,
+ *   ignoreDuplicateSlashes: true,
+ *   ignoreTrailingSlash: true,
+ *   maxParamLength: +Infinity,
+ *   allowUnsafeRegex: true,
+ *   caseSensitive: true,
+ * });
+ * http.use(async (ctx, next) => {
+ *   await next();
+ * });
+ * http.use(async (ctx, next) => {
+ *   await next();
+ * });
+ * http.use(async (ctx, next) => {
+ *   await next();
+ * });
+ * await http.listen((server) => {
+ *   console.log('Server is running on port 3000');
+ * });
+ * console.log('Server is running on port 3000');
+ */
+export declare class Http {
+    private readonly props;
+    private readonly koa;
+    private readonly loader;
+    private readonly router;
+    private server?;
+    constructor(props: HttpProps);
+    /**
+     * 获取服务端口
+     * @returns - 服务端口
+     */
+    get port(): number;
+    /**
+     * 启动服务前注册中间件
+     * @param middleware - 中间件函数
+     * @returns - 当前实例
+     */
+    use(middleware: Middleware): this;
+    /**
+     * 启动服务
+     * @param onListen - 启动服务后回调函数，可选，回调函数返回值为关闭服务回调函数
+     * @returns - 关闭服务回调函数
+     */
+    listen(onListen?: (server: Server) => void | Promise<void>): Promise<() => void>;
+    /**
+     * 注册 GET 请求路由
+     * @param url - 请求路径
+     * @param middlewares - 中间件函数
+     * @returns - 注销路由回调函数
+     */
+    get(url: string, ...middlewares: Middleware[]): () => void;
+    /**
+     * 注册 POST 请求路由
+     * @param url - 请求路径
+     * @param middlewares - 中间件函数
+     * @returns - 注销路由回调函数
+     */
+    post(url: string, ...middlewares: Middleware[]): () => void;
+    /**
+     * 注册 PUT 请求路由
+     * @param url - 请求路径
+     * @param middlewares - 中间件函数
+     * @returns - 注销路由回调函数
+     */
+    put(url: string, ...middlewares: Middleware[]): () => void;
+    /**
+     * 注册 DELETE 请求路由
+     * @param url - 请求路径
+     * @param middlewares - 中间件函数
+     * @returns - 注销路由回调函数
+     */
+    delete(url: string, ...middlewares: Middleware[]): () => void;
+    /**
+     * 注册 TRACE 请求路由
+     * @param url - 请求路径
+     * @param middlewares - 中间件函数
+     * @returns - 注销路由回调函数
+     */
+    trace(url: string, ...middlewares: Middleware[]): () => void;
+    /**
+     * 注册路由
+     * @param method 请求方法
+     * @param url 请求路径
+     * @param middlewares 中间件
+     * @returns 注销路由回调函数
+     */
+    route(method: HTTPMethod, url: string, ...middlewares: Middleware[]): () => void;
+    /**
+     * 绑定文件夹下的所有路由
+     * @param directory 文件夹路径
+     * @param options 选项
+     * @returns 注销回调
+     */
+    load(directory: string, options?: LoaderFromOptions): Promise<() => void>;
+}

package/dist/http.js

@@ -0,0 +1,161 @@
+import Koa from 'koa';
+import { randomBytes } from 'node:crypto';
+import FindMyWay from './find-my-way';
+import { createServer } from 'node:http';
+import { Loader } from './loader';
+/**
+ * Http 服务类
+ * @description - 提供 HTTP 服务的基本功能
+ * @example
+ * const http = new Http({
+ *   port: 3000,
+ *   ignoreDuplicateSlashes: true,
+ *   ignoreTrailingSlash: true,
+ *   maxParamLength: +Infinity,
+ *   allowUnsafeRegex: true,
+ *   caseSensitive: true,
+ * });
+ * http.use(async (ctx, next) => {
+ *   await next();
+ * });
+ * http.use(async (ctx, next) => {
+ *   await next();
+ * });
+ * http.use(async (ctx, next) => {
+ *   await next();
+ * });
+ * await http.listen((server) => {
+ *   console.log('Server is running on port 3000');
+ * });
+ * console.log('Server is running on port 3000');
+ */
+export class Http {
+    props;
+    koa = new Koa();
+    loader = new Loader(this);
+    router;
+    server;
+    constructor(props) {
+        this.props = props;
+        if (!this.props.keys) {
+            this.props.keys = [randomBytes(32).toString(), randomBytes(64).toString()];
+        }
+        this.koa.keys = this.props.keys;
+        this.router = FindMyWay({
+            ignoreDuplicateSlashes: this.props.ignoreDuplicateSlashes ?? true,
+            ignoreTrailingSlash: this.props.ignoreTrailingSlash ?? true,
+            maxParamLength: this.props.maxParamLength ?? +Infinity,
+            allowUnsafeRegex: this.props.allowUnsafeRegex ?? true,
+            caseSensitive: this.props.caseSensitive ?? true,
+            // @ts-ignore
+            defaultRoute: async (_, next) => await next(),
+        });
+    }
+    /**
+     * 获取服务端口
+     * @returns - 服务端口
+     */
+    get port() {
+        return this.props.port;
+    }
+    /**
+     * 启动服务前注册中间件
+     * @param middleware - 中间件函数
+     * @returns - 当前实例
+     */
+    use(middleware) {
+        this.koa.use(middleware);
+        return this;
+    }
+    /**
+     * 启动服务
+     * @param onListen - 启动服务后回调函数，可选，回调函数返回值为关闭服务回调函数
+     * @returns - 关闭服务回调函数
+     */
+    async listen(onListen) {
+        this.koa.use(this.router.routes());
+        this.server = createServer(this.koa.callback());
+        if (onListen)
+            await onListen(this.server);
+        await new Promise((resolve, reject) => {
+            this.server.listen(this.props.port, (err) => {
+                if (err)
+                    return reject(err);
+                resolve();
+            });
+        });
+        return () => {
+            this.server.close();
+        };
+    }
+    /**
+     * 注册 GET 请求路由
+     * @param url - 请求路径
+     * @param middlewares - 中间件函数
+     * @returns - 注销路由回调函数
+     */
+    get(url, ...middlewares) {
+        return this.route('GET', url, ...middlewares);
+    }
+    /**
+     * 注册 POST 请求路由
+     * @param url - 请求路径
+     * @param middlewares - 中间件函数
+     * @returns - 注销路由回调函数
+     */
+    post(url, ...middlewares) {
+        return this.route('POST', url, ...middlewares);
+    }
+    /**
+     * 注册 PUT 请求路由
+     * @param url - 请求路径
+     * @param middlewares - 中间件函数
+     * @returns - 注销路由回调函数
+     */
+    put(url, ...middlewares) {
+        return this.route('PUT', url, ...middlewares);
+    }
+    /**
+     * 注册 DELETE 请求路由
+     * @param url - 请求路径
+     * @param middlewares - 中间件函数
+     * @returns - 注销路由回调函数
+     */
+    delete(url, ...middlewares) {
+        return this.route('DELETE', url, ...middlewares);
+    }
+    /**
+     * 注册 TRACE 请求路由
+     * @param url - 请求路径
+     * @param middlewares - 中间件函数
+     * @returns - 注销路由回调函数
+     */
+    trace(url, ...middlewares) {
+        return this.route('TRACE', url, ...middlewares);
+    }
+    /**
+     * 注册路由
+     * @param method 请求方法
+     * @param url 请求路径
+     * @param middlewares 中间件
+     * @returns 注销路由回调函数
+     */
+    route(method, url, ...middlewares) {
+        this.router.on(method, url, ...middlewares);
+        return () => {
+            this.router.off(method, url);
+        };
+    }
+    /**
+     * 绑定文件夹下的所有路由
+     * @param directory 文件夹路径
+     * @param options 选项
+     * @returns 注销回调
+     */
+    load(directory, options = {
+        defaultSuffix: '/index',
+        suffix: 'controller',
+    }) {
+        return this.loader.from(directory, options);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { Http } from './http';
+export * from './http';
+export * from './find-my-way';
+export * from './controller';
+export * from './loader';
+export default Http;

package/dist/index.js

@@ -0,0 +1,6 @@
+import { Http } from './http';
+export * from './http';
+export * from './find-my-way';
+export * from './controller';
+export * from './loader';
+export default Http;

package/dist/loader.d.ts

@@ -0,0 +1,28 @@
+import { ControllerRegisterProps } from './controller';
+import { Http } from './http';
+export interface LoaderCompileOptions {
+    defaultSuffix?: string;
+    prefix?: string;
+}
+export type LoaderFromOptions = {
+    suffix?: string;
+} & LoaderCompileOptions;
+export declare class Loader {
+    private readonly http;
+    constructor(http: Http);
+    /**
+     * 单个路由绑定编译
+     * @param path 路径
+     * @param controllers 控制器数组或单个控制器
+     * @param options 选项
+     * @returns 注销回调
+     */
+    compile<R>(path: string, controllers: ControllerRegisterProps<R> | ControllerRegisterProps<R>[], options?: LoaderCompileOptions): () => void;
+    /**
+     * 文件夹批量路由绑定编译
+     * @param directory 文件夹路径
+     * @param options 选项
+     * @returns 注销回调
+     */
+    from(directory: string, options?: LoaderFromOptions): Promise<() => void>;
+}

package/dist/loader.js

@@ -0,0 +1,82 @@
+import { glob } from 'glob';
+import { resolve } from 'node:path';
+export class Loader {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * 单个路由绑定编译
+     * @param path 路径
+     * @param controllers 控制器数组或单个控制器
+     * @param options 选项
+     * @returns 注销回调
+     */
+    compile(path, controllers, options = {
+        defaultSuffix: '/index',
+    }) {
+        const callbacks = [];
+        // 格式化路径，去除默认后缀
+        const defaultSuffix = options.defaultSuffix || '/index';
+        let url = path.startsWith('/') ? path : '/' + path;
+        if (url.endsWith(defaultSuffix)) {
+            url = url.substring(0, url.length - defaultSuffix.length);
+        }
+        if (!url)
+            url = '/';
+        // 如果导出单个路由，则转化为数组，批量执行
+        if (!Array.isArray(controllers)) {
+            controllers = [controllers];
+        }
+        // 添加前缀
+        const _url = options.prefix ? options.prefix + url : url;
+        // 将路径中的参数转换为路由参数
+        const router_url = _url.replace(/\[([^\]]+)\]/g, ':$1');
+        // 批量注册路由
+        for (let i = 0; i < controllers.length; i++) {
+            const controller = controllers[i];
+            const { method, middlewares } = controller;
+            controller.data.url = router_url;
+            callbacks.push(this.http.route(method, router_url, ...middlewares));
+        }
+        // 销毁路由绑定的回调
+        return () => {
+            let j = callbacks.length;
+            while (j--)
+                callbacks[j]();
+        };
+    }
+    /**
+     * 文件夹批量路由绑定编译
+     * @param directory 文件夹路径
+     * @param options 选项
+     * @returns 注销回调
+     */
+    async from(directory, options = {
+        defaultSuffix: '/index',
+        suffix: 'controller',
+    }) {
+        const { suffix = 'controller', ...extras } = options;
+        // 获取文件夹下的所有文件
+        const files = await glob(`**/*.${suffix}.{ts,js}`, { cwd: directory });
+        // 批量注册路由
+        const callbacks = await Promise.all(files.map(async (file) => {
+            // 获取文件绝对路径
+            const path = resolve(directory, file);
+            // 获取文件地址
+            const url = file.substring(0, file.length - suffix.length - 4);
+            // 导入文件
+            const controller = await import(path);
+            // 获取文件导出的默认函数
+            const { default: fn } = controller;
+            // 注册路由
+            return this.compile(url, fn, extras);
+        }));
+        // 销毁路由绑定的回调
+        return () => {
+            let i = callbacks.length;
+            while (i--)
+                callbacks[i]();
+        };
+    }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@hile/http",
+  "description": "Hile http - HTTP service framework",
+  "version": "1.0.6",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/koa": "^3.0.1",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "find-my-way": "^9.5.0",
+    "glob": "^13.0.6",
+    "koa": "^3.1.2",
+    "koa-compose": "^4.1.0"
+  },
+  "gitHead": "16396508dcd3a71359fd8371feefb2f621a92a76"
+}