okgoes-core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,320 @@
-# Temporary Holding Version
+# okgoes-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+零远端依赖的 Node.js MVC 框架：基于 `node:http` 自研 Koa 风格内核与中间件，内置隐性路由（模块/控制器/方法自动映射）、可配置路由模式、插件系统、最小 EJS 兼容模板引擎。
+
+## 特性
+
+- **零远端依赖**：`dependencies` 为空，仅使用 Node.js 内置模块（http/https/crypto/stream/fs/path/querystring）
+- **隐性路由（约定路由）**：`/模块/控制器/方法` 自动映射到 `src/controller/{module}/{controller}.controller.ts` 的对应方法，无需注册
+- **路由模式可配置**：`routing.mode = auto | manual | both`
+- **服务端渲染**：`render()` 无参时按约定定位模板 `views/{module}/{controller}/{action}.ejs`
+- **插件系统**：`OkgoesPlugin.install(app, options)` 可注册中间件 / service
+- **控制器返回值自动响应**：返回对象转 JSON，返回字符串输出 HTML
+- **中间件顺序可控**：`app.useBefore / useAfter / useAt` 在指定核心阶段前后插入自定义中间件
+- **自定义 server / WebSocket 共用端口**：`app.callback()` / `app.startWithoutListen()` 直接拿到 koa callback
+- **约定路由 404 可定制**：`config.notFound.redirect / handler` 或 `app.koa.on("notFound", ctx => ...)`
+- **内置反向代理**：`config.proxy` 拦截指定路径前缀，流式转发到 Java/Go/Python 等后端，支持路径重写、changeOrigin、https、自定义头，避免前端跨域
+- **debug 模式 + 全局异常捕获**：`config.debug` 输出完整堆栈/请求详情/视图渲染错误；`config.error` 支持 handler / byStatus / redirect / render 错误页 / 进程级异常捕获
+- 内置 session / cors / 静态资源 / body 解析 / 访问日志，均为自研实现，可配置开关
+
+## 快速开始
+
+```bash
+npm install okgoes-core okgoes-cli -D
+npx okgoes create my-app
+cd my-app && npm install && npm run dev
+```
+
+## 目录约定
+
+```
+src/
+  config/index.ts            # 应用配置
+  controller/index.controller.ts      # GET /            -> index()
+  controller/admin/post.controller.ts # GET /admin/post  -> index()
+  model/user.model.ts        # 继承 Model
+  middleware/auth.ts         # 自定义中间件
+  plugin/metrics.ts          # 自定义插件
+  routes.ts                  # 显式路由（manual/both 模式）
+views/index/index.ejs        # 约定模板
+public/                      # 静态资源
+```
+
+## 路由配置
+
+```ts
+// src/config/index.ts
+const config: AppConfig = {
+    routing: {
+        mode: "auto",          // auto: 隐性路由 | manual: 显式路由 | both
+        defaultController: "index",
+        defaultAction: "index",
+        modules: ["admin"],    // 模块白名单，URL 首段命中才解析为模块
+    },
+};
+```
+
+- 约定路由：`/admin/user/read/1` → `admin/user.controller.ts` 的 `read()`，附加段通过 `request.getRouteArgs()` 获取
+- 显式路由：
+
+```ts
+// src/routes.ts
+export default function register(router: Router) {
+    router.get("/api/users/:id", UserController, "read");
+}
+```
+
+显式路由 `:id` 自动注入 `request.params.id`；`both` 模式显式优先、隐性兜底。
+
+## HTTP 方法限制
+
+```ts
+import { Controller, Get, Post } from "okgoes-core";
+
+export default class IndexController extends Controller {
+    @Get()
+    async info() {
+        return { ok: true }; // 仅 GET，其他方法返回 405；返回对象自动 JSON
+    }
+
+    @Post()
+    async create() {
+        return this.service("repository").save(this.req.getBody());
+    }
+}
+```
+
+`this.req` / `this.res` / `this.context` / `this.application` 是 `initialize()` 后非 null 的 getter，
+无需 `this.request?.` 或 `this.ctx!` 噪音。`this.request` / `this.ctx` 等原字段仍保留以兼容。
+
+## 渲染
+
+```ts
+async index() {
+    await this.render({ title: "hi" });            // 约定定位 views/index/index.ejs
+    await this.render("admin/list", { list: [] }); // 指定模板
+    await this.renderAction("markdown", { doc });  // 切换到同控制器下 markdown action 的模板
+}
+```
+
+## 中间件装配顺序
+
+默认装配顺序（核心阶段名常量 `CoreMiddleware`）：
+
+```
+error → accessLog → cors → session → body → views → static
+```
+
+`app.use(fn)` 推入的自定义中间件晚于所有核心中间件。如需在核心阶段前后插入（例如鉴权先于 CORS）：
+
+```ts
+import { Application, CoreMiddleware } from "okgoes-core";
+
+const app = new Application(baseDir, config);
+app.useBefore(CoreMiddleware.Cors, authMiddleware);  // 鉴权先于 CORS，鉴权失败不返回 CORS 头
+app.useAfter(CoreMiddleware.Session, requestIdMiddleware);
+```
+
+## debug 模式与全局异常捕获
+
+### debug 模式
+
+```ts
+new Application(baseDir, { debug: true });
+```
+
+开启后：
+- 错误响应体包含 `stack`、`request`（method/url/path/query/headers）
+- 视图渲染错误附加 `template` 路径与 `viewExtension`，便于定位是哪个模板出错
+- 日志输出完整错误对象（含堆栈）
+- 关闭时 5xx 仅返回 `{ code, message: "Internal Server Error" }`，不暴露内部信息；4xx 或 `err.expose = true` 仍暴露 message
+
+### 全局异常捕获
+
+```ts
+new Application(baseDir, {
+    error: {
+        handler: (err, ctx) => { ctx.status = 500; ctx.body = { code: 500, msg: err.message }; },
+        byStatus: { 404: { redirect: "/page/404" }, 500: { handler: (err, ctx) => ctx.redirect("/page/500") } },
+        redirect: "/oops",
+        render: true,
+        expose: false,
+    },
+});
+```
+
+处理优先级：`handler` > `byStatus[code]` > `redirect` > `render` > 默认 JSON 响应。
+
+错误页模板可访问 `{ status, err, message, stack }`（stack 仅 debug 模式传入）：
+
+```ejs
+<!-- views/error/500.ejs -->
+<h1><%= status %></h1>
+<p><%= message %></p>
+<% if (stack) { %><pre><%= stack %></pre><% } %>
+```
+
+### 进程级未捕获异常
+
+```ts
+app.captureProcessErrors({ exit: true, onUncaught: (err) => {}, onUnhandled: (reason) => {} });
+```
+
+也可在中间件内手动调用 `app.handleError(err, ctx)` 走统一异常处理链。
+
+## 自定义 404
+
+```ts
+const app = new Application(baseDir, {
+    notFound: { redirect: "/page/404" },            // 友好 404 页面
+    // 或
+    notFound: { handler: (ctx) => { ctx.body = { code: 404 }; } },
+});
+
+// 或事件式
+app.koa.on("notFound", (ctx) => ctx.redirect("/page/404"));
+```
+
+## 反向代理（转发到 Java/Go/Python 等后端）
+
+后端渲染场景下，API 可能由其他语言的后端提供。通过 `config.proxy` 拦截指定路径前缀，
+流式转发到目标后端，前端同源访问 `/api/xxx` 即可，无需 CORS。
+
+```ts
+const app = new Application(baseDir, {
+    proxy: {
+        "/api": {
+            target: "http://localhost:8080",       // Java 后端
+            rewrite: (p) => p.replace(/^\/api/, ""), // /api/users -> /users
+        },
+        "/java": {
+            target: "https://java-backend.internal",
+            pathRewrite: { "^/java": "/v1" },      // /java/items -> /v1/items
+            headers: { "X-Source": "okgoes" },     // 附加请求头
+        },
+        "/upstream": {
+            target: "http://127.0.0.1:9000",
+            changeOrigin: true,                    // 改 Host 为目标 host（默认 true）
+            timeout: 30000,                        // 30s 超时返回 504
+        },
+    },
+});
+```
+
+也可单独挂载中间件：
+
+```ts
+import { createProxy } from "okgoes-core";
+app.use(createProxy({ "/api": { target: "http://localhost:8080" } }));
+```
+
+说明：
+- 代理在 body 解析之前执行，命中后直接流式转发原始请求体，不调 `next()`
+- 自动注入 `X-Forwarded-For / Host / Proto` 头
+- 目标不可达返回 502，超时返回 504
+- 支持 https 目标（`secure: true` 校验证书，默认不校验，便于内网自签）
+- `filter` 可按 ctx 条件决定是否命中（如仅代理 GET）
+- 装配阶段为 `CoreMiddleware.Proxy`，可用 `app.useBefore / useAfter` 在其前后插入自定义逻辑
+
+## 自定义 server / WebSocket 共用端口
+
+```ts
+import * as http from "http";
+import { WebSocketServer } from "ws";
+import { Application } from "okgoes-core";
+
+const app = new Application(baseDir, config);
+const koa = await app.startWithoutListen();
+const server = http.createServer(koa.callback());
+new WebSocketServer({ server });
+server.listen(3000);
+```
+
+或直接 `app.callback()` 拿到 koa callback 用于 `http.createServer`。
+
+## 自定义调度（dispatch）
+
+`Application.dispatch(controllerClass, actionName, ctx, resolvedRoute?, routeParams?)` 可独立调用，
+自动处理：实例化、initialize、HTTP method 装饰器约束、返回值自动响应（对象→JSON，字符串→HTML）。
+
+```ts
+// 自定义 404 重定向 + 权限前置 + 约定路由兜底
+app.use(async (ctx, next) => {
+    const resolver = app.createRouteResolver(ctx.path);
+    const route = resolver.getResolvedRoute();
+    ctx.state.resolvedRoute = route;
+    if (!await hasPermission(route)) { ctx.redirect("/login"); return; }
+    const ControllerClass = loadControllerClass(...);
+    if (!ControllerClass) { ctx.redirect("/page/404"); return; }
+    await app.dispatch(ControllerClass, route.actionName, ctx, route);
+});
+```
+
+也可用导出的 `createConventionRouter({ baseDir, routing, notFound })` 工厂单独创建约定路由中间件。
+
+## bare 模式 / 完全手动装配
+
+```ts
+new Application(baseDir, { bare: true });        // 跳过所有核心中间件自动装配
+// 等价
+new Application(baseDir, { autoLoad: false });
+```
+
+## ctx 自定义属性类型扩展
+
+框架自身把 `resolvedRoute` 写入 `ctx.state.resolvedRoute`，业务方可通过 `declare module` 扩展：
+
+```ts
+declare module "okgoes-core" {
+    interface ContextState {
+        userId?: number;
+    }
+}
+// 中间件内 ctx.state.userId 有类型
+```
+
+## 插件
+
+```ts
+export default function metricsPlugin(): OkgoesPlugin {
+    return {
+        name: "metrics",
+        install(app, options) {
+            let count = 0;
+            app.service("metrics", { count: () => count }); // controller 内 this.service("metrics")
+            app.use(async (ctx, next) => { count++; await next(); });
+        },
+    };
+}
+
+app.usePlugin(metricsPlugin(), { prefix: "[demo]" });
+```
+
+## CORS `allowHeaders: "*"` 行为说明
+
+当 `allowHeaders` 未提供时，框架透传请求头 `Access-Control-Request-Headers`（兼容 `credentials: true`）。
+显式传 `"*"` 会原样写入 `Access-Control-Allow-Headers: *`；按 CORS 规范，`*` 与 `credentials: true` 同时使用时
+部分浏览器不生效，建议省略 `allowHeaders` 或显式列出所需头。
+
+## API 速查
+
+| 名称 | 说明 |
+|------|------|
+| `Application.use(fn)` | 推入自定义中间件（晚于核心中间件） |
+| `Application.useBefore(stage, fn)` | 在核心阶段之前插入 |
+| `Application.useAfter(stage, fn)` | 在核心阶段之后插入 |
+| `Application.useAt(stage, fn)` | 等价于 useBefore |
+| `Application.callback()` | 返回 koa callback，用于自定义 server |
+| `Application.startWithoutListen()` | 装配但不 listen，返回 koa 实例 |
+| `Application.dispatch(...)` | 手动调度控制器 action |
+| `Application.createConventionRouteMiddleware()` | 取出约定路由中间件（public） |
+| `Application.getRoutingConfig()` | 暴露路由配置，避免多处定义 |
+| `Application.createRouteResolver(pathname)` | 复用 app config 创建 RouteResolver |
+| `createConventionRouter({ baseDir, routing, notFound })` | 独立创建约定路由中间件工厂 |
+| `createProxy(options)` | 反向代理中间件工厂，键为路径前缀 |
+| `Application.handleError(err, ctx)` | 手动触发统一异常处理链 |
+| `Application.captureProcessErrors(opts)` | 挂接进程级 uncaughtException / unhandledRejection |
+| `CoreMiddleware` | 核心中间件阶段名常量 |
+| `HttpMethod` | HTTP 方法常量与类型 |
+| `UploadedFile` | 上传文件类型 |
+| `Koa` | 底层内核类（已导出） |

package/dist/application.d.ts

@@ -0,0 +1,101 @@
+import Koa from "./core/koa";
+import Context from "./core/context";
+import { AppConfig, Middleware, OkgoesPlugin, ResolvedRoute, RoutingConfig } from "./types";
+import { ResolvedConfig } from "./config";
+import RouteResolver from "./route-resolver";
+import Router from "./router";
+import { CoreMiddlewareName } from "./constants";
+export interface OkgoesLogger {
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+}
+export { CoreMiddleware, CoreMiddlewareName } from "./constants";
+export default class Application {
+    readonly baseDir: string;
+    readonly koa: Koa;
+    readonly router: Router;
+    config: ResolvedConfig;
+    logger: OkgoesLogger;
+    private readonly services;
+    private readonly customMiddlewares;
+    private readonly stagedMiddlewares;
+    private readonly pluginRegistrations;
+    private isStarted;
+    constructor(baseDir: string, config?: AppConfig);
+    use(middleware: Middleware): this;
+    /**
+     * 在指定核心中间件之前插入自定义中间件。
+     * 例：app.useBefore("cors", authMiddleware) 让鉴权先于 CORS 执行。
+     * 必须在 start() 之前调用。
+     */
+    useBefore(stage: CoreMiddlewareName | string, middleware: Middleware): this;
+    /** 在指定核心中间件之后插入自定义中间件。 */
+    useAfter(stage: CoreMiddlewareName | string, middleware: Middleware): this;
+    /** 在指定核心中间件位置插入（替换语义：在该阶段之前执行）。等价于 useBefore。 */
+    useAt(stage: CoreMiddlewareName | string, middleware: Middleware): this;
+    usePlugin(plugin: OkgoesPlugin, options?: any): this;
+    service(name: string, instance: any): this;
+    getService<T = any>(name: string): T;
+    hasService(name: string): boolean;
+    get controllerBaseDir(): string;
+    /** 暴露路由配置，供外部构造 RouteResolver 时复用，避免多处定义不一致。 */
+    getRoutingConfig(): RoutingConfig;
+    /** 复用 app 的 config 创建 RouteResolver，避免每次手动构造 RoutingConfig。 */
+    createRouteResolver(pathname: string): RouteResolver;
+    /** 直接返回 koa callback，用于 http.createServer(app.callback()) 自定义 server / WebSocket 共用端口。 */
+    callback(): (req: any, res: any) => void;
+    /**
+     * 装配中间件但不 listen，返回 koa 实例。
+     * 用于 WebSocket / HTTPS / 自定义 server 场景：const server = http.createServer(app.startWithoutListen().callback());
+     */
+    startWithoutListen(): Promise<Koa>;
+    start(): Promise<Koa>;
+    private ensureMiddlewaresMounted;
+    /**
+     * 装配核心中间件与分阶段插入的自定义中间件。
+     * 顺序：error → [before/after error] → accessLog → ... → static → [after static]
+     * bare 模式下跳过所有核心中间件，仅保留 error 兜底与分阶段插入项。
+     */
+    private assembleMiddlewares;
+    private createProxyMiddleware;
+    private createViewsMiddleware;
+    private createStaticMiddleware;
+    private flushStagedBefore;
+    private flushStagedAfter;
+    private flushStagedAround;
+    private createErrorHandlerMiddleware;
+    /**
+     * 全局异常统一入口。处理优先级：
+     * handler > byStatus[code] > redirect > render > 默认响应。
+     * debug 模式输出完整堆栈与请求详情；非 debug 仅暴露 4xx 或 err.expose 的 message。
+     */
+    handleError(err: any, ctx: Context): Promise<void>;
+    /** 渲染约定错误页 views/error/{status}.ext，模板不存在时返回 false 回退默认响应 */
+    private renderErrorPage;
+    /** 默认错误响应体：debug 或 expose 时输出详情，否则仅暴露 4xx / err.expose 的 message */
+    private writeDefaultErrorBody;
+    /**
+     * 可选挂接进程级未捕获异常（uncaughtException / unhandledRejection）。
+     * 默认仅日志记录不退出进程；传入 { exit: true } 时在 uncaughtException 后退出，
+     * 便于配合 PM2 / systemd 等进程管理器自动重启。
+     */
+    captureProcessErrors(options?: {
+        exit?: boolean;
+        onUncaught?: (err: Error) => void;
+        onUnhandled?: (err: any) => void;
+    }): this;
+    /** 约定路由 / dispatch 命中失败时统一走此处的 404 处理，支持 redirect / handler / 事件。 */
+    private handleNotFound;
+    private createAccessLogMiddleware;
+    private mountRouterLayer;
+    private resolveSourceFile;
+    /**
+     * 约定路由中间件（public，可单独取出用于自定义调度）。
+     * 解析 URL → 定位控制器文件 → 加载控制器类 → dispatch。
+     * 控制器不存在时调用 next()，由 error handler 兜底为 404。
+     */
+    createConventionRouteMiddleware(): Middleware;
+    /** 实例化控制器、注入请求响应并执行 action，返回值自动写入响应 */
+    dispatch(controllerClass: new () => any, actionName: string, ctx: Context, resolvedRoute?: ResolvedRoute | null, routeParams?: Record<string, string>): Promise<void>;
+}