okgoes-core 0.0.0-stage → 2.0.0

package/README.md

@@ -1,3 +1,106 @@
-# 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
+- 内置 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.request.getBody());
+    }
+}
+```
+
+## 插件
+
+```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]" });
+```
+
+## 渲染
+
+```ts
+async index() {
+    await this.render({ title: "hi" });            // 约定定位 views/index/index.ejs
+    await this.render("admin/list", { list: [] }); // 指定模板
+}
+```

package/dist/application.d.ts

@@ -0,0 +1,37 @@
+import Koa from "./core/koa";
+import Context from "./core/context";
+import { AppConfig, Middleware, OkgoesPlugin, ResolvedRoute } from "./types";
+import { ResolvedConfig } from "./config";
+import Router from "./router";
+export interface OkgoesLogger {
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+}
+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 pluginRegistrations;
+    private isStarted;
+    constructor(baseDir: string, config?: AppConfig);
+    use(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;
+    start(): Promise<Koa>;
+    private buildCoreMiddlewares;
+    private createErrorHandlerMiddleware;
+    private createAccessLogMiddleware;
+    private mountRouterLayer;
+    private resolveSourceFile;
+    private createConventionRouteMiddleware;
+    /** 实例化控制器、注入请求响应并执行 action，返回值自动写入响应 */
+    dispatch(controllerClass: new () => any, actionName: string, ctx: Context, resolvedRoute?: ResolvedRoute | null, routeParams?: Record<string, string>): Promise<void>;
+}

package/dist/application.js

@@ -0,0 +1,279 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const koa_1 = __importDefault(require("./core/koa"));
+const cors_1 = __importDefault(require("./middleware/cors"));
+const session_1 = __importDefault(require("./middleware/session"));
+const body_1 = require("./middleware/body");
+const static_1 = __importDefault(require("./middleware/static"));
+const views_1 = __importDefault(require("./middleware/views"));
+const config_1 = require("./config");
+const route_resolver_1 = __importDefault(require("./route-resolver"));
+const router_1 = __importDefault(require("./router"));
+const request_1 = __importDefault(require("./request"));
+const response_1 = __importDefault(require("./response"));
+const loader_1 = require("./loader");
+const decorators_1 = require("./decorators");
+const constants_1 = require("./constants");
+class Application {
+    constructor(baseDir, config = {}) {
+        this.logger = console;
+        this.services = new Map();
+        this.customMiddlewares = [];
+        this.pluginRegistrations = [];
+        this.isStarted = false;
+        this.baseDir = baseDir;
+        this.config = (0, config_1.mergeConfig)(config);
+        this.koa = new koa_1.default();
+        this.router = new router_1.default(this);
+        this.koa[constants_1.FRAMEWORK_INSTANCE_KEY] = this;
+    }
+    use(middleware) {
+        this.customMiddlewares.push(middleware);
+        return this;
+    }
+    usePlugin(plugin, options) {
+        if (!plugin || !plugin.name || typeof plugin.install !== "function") {
+            throw new Error("plugin must have name and install(app, options)");
+        }
+        this.pluginRegistrations.push({ plugin, options });
+        return this;
+    }
+    service(name, instance) {
+        this.services.set(name, instance);
+        return this;
+    }
+    getService(name) {
+        if (!this.services.has(name)) {
+            throw new Error(`service [${name}] is not registered`);
+        }
+        return this.services.get(name);
+    }
+    hasService(name) {
+        return this.services.has(name);
+    }
+    get controllerBaseDir() {
+        return path.join(this.baseDir, this.config.controllerDir);
+    }
+    async start() {
+        if (this.isStarted) {
+            throw new Error("application has already started");
+        }
+        this.isStarted = true;
+        for (const middleware of this.buildCoreMiddlewares()) {
+            this.koa.use(middleware);
+        }
+        for (const { plugin, options } of this.pluginRegistrations) {
+            await plugin.install(this, options);
+            this.logger.info(`[okgoes] plugin "${plugin.name}" loaded`);
+        }
+        for (const middleware of this.customMiddlewares) {
+            this.koa.use(middleware);
+        }
+        this.mountRouterLayer();
+        return new Promise((resolve) => {
+            const { port, host } = this.config;
+            this.koa.listen(port, host, () => {
+                this.logger.info(`[okgoes] server started at http://localhost:${port} (routing: ${this.config.routing.mode})`);
+                resolve(this.koa);
+            });
+        });
+    }
+    buildCoreMiddlewares() {
+        const koaApp = this.koa;
+        const { session: sessionConfig, static: staticConfig } = this.config;
+        const middlewares = [];
+        koaApp.keys = [this.config.session.secret];
+        koaApp.on("error", (err, ctx) => {
+            this.logger.error("[okgoes] server error", (ctx && ctx.path) || "", err);
+        });
+        middlewares.push(this.createErrorHandlerMiddleware());
+        if (this.config.log.enable) {
+            middlewares.push(this.createAccessLogMiddleware());
+        }
+        if (this.config.cors.enable) {
+            middlewares.push((0, cors_1.default)({ origin: "*", allowMethods: "*", credentials: true }));
+        }
+        if (sessionConfig.enable) {
+            middlewares.push((0, session_1.default)({
+                key: sessionConfig.key,
+                maxAge: sessionConfig.maxAge,
+                signed: true,
+                renew: true,
+            }, koaApp));
+        }
+        middlewares.push((0, body_1.koaBody)({
+            jsonLimit: "2mb",
+            formLimit: "2mb",
+            textLimit: "2mb",
+            multipart: true,
+            urlencoded: true,
+            text: true,
+            json: true,
+        }));
+        const viewDirectory = path.join(this.baseDir, this.config.view.dir);
+        if (fs.existsSync(viewDirectory)) {
+            koaApp[constants_1.APP_VIEW_EXTENSION_KEY] = this.config.view.extension;
+            middlewares.push((0, views_1.default)(viewDirectory, {
+                extension: this.config.view.extension,
+            }));
+        }
+        if (staticConfig.enable) {
+            const publicDirectory = path.join(this.baseDir, staticConfig.dir);
+            if (fs.existsSync(publicDirectory)) {
+                middlewares.push((0, static_1.default)(publicDirectory, { maxAge: staticConfig.maxAge }));
+            }
+        }
+        return middlewares;
+    }
+    createErrorHandlerMiddleware() {
+        return async (ctx, next) => {
+            try {
+                await next();
+                if (ctx.status === 404 && ctx.body === undefined) {
+                    ctx.status = 404;
+                    ctx.body = "404 Not Found";
+                }
+            }
+            catch (err) {
+                this.logger.error(`[okgoes] ${ctx.method} ${ctx.path}`, err);
+                if (!ctx.headerSent) {
+                    ctx.status = err.status || 500;
+                    ctx.body = { code: err.status || 500, message: err.message || "Internal Server Error" };
+                }
+            }
+        };
+    }
+    createAccessLogMiddleware() {
+        return async (ctx, next) => {
+            const startedAt = Date.now();
+            await next();
+            const elapsedMs = Date.now() - startedAt;
+            ctx.set("X-Response-Time", `${elapsedMs}ms`);
+            this.logger.info(`[okgoes] ${ctx.method} ${ctx.originalUrl} ${ctx.status} ${elapsedMs}ms`);
+        };
+    }
+    mountRouterLayer() {
+        const mode = this.config.routing.mode;
+        if (mode === "manual" || mode === "both") {
+            const routesFile = this.resolveSourceFile(path.join(this.baseDir, "src/routes"));
+            if (routesFile) {
+                const loaded = require(routesFile);
+                const registerRoutes = loaded && (loaded.default || loaded);
+                if (typeof registerRoutes === "function") {
+                    registerRoutes(this.router);
+                }
+            }
+            else {
+                this.logger.warn(`[okgoes] routing.mode=${mode}, but src/routes.ts was not found`);
+            }
+            this.koa.use(this.router.createMiddleware());
+        }
+        if (mode === "auto" || mode === "both") {
+            this.koa.use(this.createConventionRouteMiddleware());
+        }
+        if (mode === "manual") {
+            this.koa.use(async (ctx) => {
+                ctx.status = 404;
+                ctx.body = "404 Not Found";
+            });
+        }
+    }
+    resolveSourceFile(filePathWithoutExtension) {
+        for (const extension of [".js", ".ts"]) {
+            const candidate = `${filePathWithoutExtension}${extension}`;
+            if (fs.existsSync(candidate) && !/\.d\.ts$/.test(candidate)) {
+                return candidate;
+            }
+        }
+        return null;
+    }
+    createConventionRouteMiddleware() {
+        return async (ctx, next) => {
+            const resolvedRoute = new route_resolver_1.default(ctx.path, this.config.routing).getResolvedRoute();
+            ctx[constants_1.CTX_RESOLVED_ROUTE_KEY] = resolvedRoute;
+            const controllerFile = (0, loader_1.resolveControllerFile)(this.controllerBaseDir, resolvedRoute.moduleName, resolvedRoute.controllerName);
+            if (!controllerFile) {
+                await next();
+                return;
+            }
+            const controllerClass = (0, loader_1.loadControllerClass)(controllerFile);
+            if (!controllerClass) {
+                await next();
+                return;
+            }
+            await this.dispatch(controllerClass, resolvedRoute.actionName, ctx, resolvedRoute);
+        };
+    }
+    /** 实例化控制器、注入请求响应并执行 action，返回值自动写入响应 */
+    async dispatch(controllerClass, actionName, ctx, resolvedRoute = null, routeParams) {
+        const response = new response_1.default(ctx);
+        response.setResolvedRoute(resolvedRoute);
+        const controller = new controllerClass();
+        if (typeof controller[actionName] !== "function") {
+            ctx.status = 404;
+            ctx.body = "404 action not found";
+            return;
+        }
+        const requiredMethod = (0, decorators_1.resolveHttpMethodConstraint)(controllerClass, actionName);
+        if (requiredMethod !== "all" && requiredMethod !== ctx.method.toLowerCase()) {
+            ctx.status = 405;
+            ctx.body = "405 Method Not Allowed";
+            return;
+        }
+        const request = new request_1.default(ctx);
+        request.setResolvedRoute(resolvedRoute);
+        if (routeParams) {
+            request.routeParams = routeParams;
+        }
+        controller.initialize(ctx, request, response, this);
+        const returned = controller[actionName]();
+        const result = returned instanceof Promise ? await returned : returned;
+        if (result !== undefined && ctx.body === undefined && !ctx.headerSent) {
+            if (typeof result === "string") {
+                response.html(result);
+            }
+            else {
+                response.json(result);
+            }
+        }
+    }
+}
+exports.default = Application;

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+import { AppConfig, RoutingConfig } from "./types";
+export interface ResolvedConfig {
+    port: number;
+    host: string;
+    controllerDir: string;
+    routing: RoutingConfig;
+    view: {
+        dir: string;
+        extension: string;
+    };
+    session: {
+        enable: boolean;
+        key: string;
+        maxAge: number;
+        secret: string;
+    };
+    cors: {
+        enable: boolean;
+    };
+    static: {
+        enable: boolean;
+        dir: string;
+        maxAge: number;
+    };
+    log: {
+        enable: boolean;
+    };
+}
+export declare const defaultConfig: ResolvedConfig;
+export declare function mergeConfig(userConfig?: AppConfig): ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfig = void 0;
+exports.mergeConfig = mergeConfig;
+exports.defaultConfig = {
+    port: 3000,
+    host: "0.0.0.0",
+    controllerDir: "src/controller",
+    routing: {
+        mode: "auto",
+        defaultModule: "default",
+        defaultController: "index",
+        defaultAction: "index",
+        modules: [],
+    },
+    view: { dir: "views", extension: "ejs" },
+    session: { enable: false, key: "okgoes", maxAge: 3600000, secret: "okgoes secret" },
+    cors: { enable: false },
+    static: { enable: true, dir: "public", maxAge: 1000 * 60 * 60 * 24 },
+    log: { enable: true },
+};
+function mergeConfig(userConfig = {}) {
+    const pick = (value, fallback) => value ?? fallback;
+    return {
+        port: pick(userConfig.port, exports.defaultConfig.port),
+        host: pick(userConfig.host, exports.defaultConfig.host),
+        controllerDir: pick(userConfig.controllerDir, exports.defaultConfig.controllerDir),
+        routing: {
+            mode: pick(userConfig.routing?.mode, exports.defaultConfig.routing.mode),
+            defaultModule: pick(userConfig.routing?.defaultModule, exports.defaultConfig.routing.defaultModule),
+            defaultController: pick(userConfig.routing?.defaultController, exports.defaultConfig.routing.defaultController),
+            defaultAction: pick(userConfig.routing?.defaultAction, exports.defaultConfig.routing.defaultAction),
+            modules: pick(userConfig.routing?.modules, []),
+        },
+        view: {
+            dir: pick(userConfig.view?.dir, exports.defaultConfig.view.dir),
+            extension: pick(userConfig.view?.extension, exports.defaultConfig.view.extension),
+        },
+        session: {
+            enable: pick(userConfig.session?.enable, exports.defaultConfig.session.enable),
+            key: pick(userConfig.session?.key, exports.defaultConfig.session.key),
+            maxAge: pick(userConfig.session?.maxAge, exports.defaultConfig.session.maxAge),
+            secret: pick(userConfig.session?.secret, exports.defaultConfig.session.secret),
+        },
+        cors: {
+            enable: pick(userConfig.cors?.enable, exports.defaultConfig.cors.enable),
+        },
+        static: {
+            enable: pick(userConfig.static?.enable, exports.defaultConfig.static.enable),
+            dir: pick(userConfig.static?.dir, exports.defaultConfig.static.dir),
+            maxAge: pick(userConfig.static?.maxAge, exports.defaultConfig.static.maxAge),
+        },
+        log: {
+            enable: pick(userConfig.log?.enable, exports.defaultConfig.log.enable),
+        },
+    };
+}

package/dist/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const FRAMEWORK_INSTANCE_KEY = "okgoes";
+export declare const APP_VIEW_EXTENSION_KEY = "okgoesViewExt";
+export declare const CTX_RESOLVED_ROUTE_KEY = "okgoesResolvedRoute";

package/dist/constants.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CTX_RESOLVED_ROUTE_KEY = exports.APP_VIEW_EXTENSION_KEY = exports.FRAMEWORK_INSTANCE_KEY = void 0;
+exports.FRAMEWORK_INSTANCE_KEY = "okgoes";
+exports.APP_VIEW_EXTENSION_KEY = "okgoesViewExt";
+exports.CTX_RESOLVED_ROUTE_KEY = "okgoesResolvedRoute";

package/dist/controller.d.ts

@@ -0,0 +1,17 @@
+import type Context from "./core/context";
+import Request from "./request";
+import Response from "./response";
+import type Application from "./application";
+export default class Controller {
+    request: Request | null;
+    response: Response | null;
+    ctx: Context | null;
+    app: Application | null;
+    initialize(ctx: Context, request: Request, response: Response, app: Application): void;
+    protected render(templateOrLocals?: string | object, locals?: any): Promise<void>;
+    protected json(data: any): void;
+    protected text(content: string): void;
+    protected html(content: string): void;
+    protected redirect(location: string): void;
+    protected service<T = any>(name: string): T;
+}

package/dist/controller.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class Controller {
+    constructor() {
+        this.request = null;
+        this.response = null;
+        this.ctx = null;
+        this.app = null;
+    }
+    initialize(ctx, request, response, app) {
+        this.ctx = ctx;
+        this.request = request;
+        this.response = response;
+        this.app = app;
+    }
+    async render(templateOrLocals, locals) {
+        if (typeof templateOrLocals === "object") {
+            await this.response?.render(undefined, templateOrLocals);
+        }
+        else {
+            await this.response?.render(templateOrLocals, locals);
+        }
+    }
+    json(data) {
+        this.response?.json(data);
+    }
+    text(content) {
+        this.response?.text(content);
+    }
+    html(content) {
+        this.response?.html(content);
+    }
+    redirect(location) {
+        this.response?.redirect(location);
+    }
+    service(name) {
+        if (!this.app) {
+            throw new Error("controller is not bound to an application, cannot resolve service");
+        }
+        return this.app.getService(name);
+    }
+}
+exports.default = Controller;

package/dist/core/compose.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 中间件洋葱模型组合器（等价于 koa-compose，零远端依赖实现）。
+ * 依次执行中间件，next() 触发下一个中间件，await next() 后回到当前中间件形成洋葱结构。
+ */
+export type Next = () => Promise<any>;
+export type MiddlewareFn<C = any> = (ctx: C, next: Next) => any;
+export declare function compose<C = any>(middleware: MiddlewareFn<C>[]): (ctx: C, next?: Next) => Promise<any>;

package/dist/core/compose.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compose = compose;
+function compose(middleware) {
+    if (!Array.isArray(middleware)) {
+        throw new TypeError("middleware stack must be an array");
+    }
+    for (const fn of middleware) {
+        if (typeof fn !== "function") {
+            throw new TypeError("middleware must be composed of functions");
+        }
+    }
+    return function composed(ctx, next) {
+        let index = -1;
+        function dispatch(i) {
+            if (i <= index) {
+                return Promise.reject(new Error("next() called multiple times"));
+            }
+            index = i;
+            let fn = middleware[i];
+            if (i === middleware.length) {
+                fn = next;
+            }
+            if (!fn) {
+                return Promise.resolve();
+            }
+            try {
+                return Promise.resolve(fn(ctx, () => dispatch(i + 1)));
+            }
+            catch (err) {
+                return Promise.reject(err);
+            }
+        }
+        return dispatch(0);
+    };
+}