⚡ @hashan-cn/super-node-core

Zero-Config Koa Application Core — 从目录结构一键 Bootstrap 你的 Node.js 服务。

@hashan-cn/super-node-core 是一个 约定优于配置 的 Koa 核心框架，只要按照约定创建 app/ 和 config/ 目录，就可以自动加载：

• Controller / Service / Middleware / Extend / Router / Router-Schema / Plugin
• 多环境配置（local / beta / production）
• Koa Router 路由注册 与全局中间件接入

让你专注写业务，而不是手撸重复的启动脚本和 Loader。

🧰 Tech Stack / 技术栈

• Runtime: Node.js >= 14
• Web Framework: [email protected]
• Router: koa-router@^7.4.0
• File System Loader: glob@^7.1.4
• Architecture: Convention-based, 自动扫描并挂载业务模块

🚀 Quick Start / 快速开始

• 安装

npm install @hashan-cn/super-node-core
# or
yarn add @hashan-cn/super-node-core

• 目录结构约定

在你的项目根目录（即 process.cwd()）下，按如下约定组织文件：

your-project/
  app/
    controller/
    service/
    middleware/
    extend/
    router/
    router-schema/
    plugins/
    middleware.js       # 可选：全局中间件入口
  config/
    config.default.js   # 默认配置（必须）
    config.local.js     # 本地环境（可选）
    config.beta.js      # 测试环境（可选）
    config.prod.js      # 生产环境（可选）
    plugin.js           # 插件配置（可选）
  index.js              # 你的应用入口

• 一行代码启动 Koa

// index.js
const core = require('@hashan-cn/super-node-core');

core.start({
  // 应用级别配置，会注入到 app.options
  homePage: '/',           // 未匹配路由时的重定向首页
});

启动命令示例（根据环境变量自动切换配置）：

# 本地
set _ENV=local && node index.js

# 测试
set _ENV=beta && node index.js

# 生产
set _ENV=production && node index.js

🧠 Core Concepts / 核心能力

• 🌍 环境管理 env

  • 通过 process.env._ENV 获取当前运行环境
  • 提供：
    • app.env.isLocal()
    • app.env.isBeta()
    • app.env.isProduction()
    • app.env.get() → "local" | "beta" | "production"

• ⚙ 配置加载 loader/config

  • 按环境自动合并配置：
    • config.default.js + config.[local|beta|prod].js
  • 最终挂载到：
    • app.config

• 🧩 Controller / Service / Middleware Loader

  约定式扫描并挂载：

  • app/controller/**/**.js → app.controller.xxx.yyy
  • app/service/**/**.js → app.service.xxx.yyy
  • app/middleware/**/**.js → app.middlewares.xxx.yyy
  • app/extend/**/**.js → 直接挂到 app[extendName]

  支持 目录 + 文件名自动驼峰转换：
  例如 app/controller/user-center/user-login.js 将映射为：

  app.controller.userCenter.userLogin

• 📡 Router & Router Schema

  • app/router/**/**.js → 由 koa-router 自动注册所有路由
  • app/router-schema/**/**.js → 合并为 app.routerSchema，配合 AJV 做参数校验

• 🔌 Plugin System

  • 通过 config/plugin.js 声明插件：

  // config/plugin.js
  module.exports = {
    mysql: {
      enable: true,
      path: './app/plugins/mysql.js',
      config: { /* ... */ },
    },
  };

  • 插件实例会被挂到：

    • app.plugins.mysql
    • app.context.mysql（在 Koa ctx 中直接使用）

  • 若插件实例实现 close() 方法，将自动加入 app.closers，方便优雅退出。

🏁 API

• start(options?: object): KoaApp

const core = require('@hashan-cn/super-node-core');

const app = core.start({
  homePage: '/',          // 未匹配路由时的重定向地址
  // ...更多自定义 options，都会挂到 app.options 上
});

内部做了这些事：

• 创建 koa 实例并设置：
  • app.baseDir = process.cwd()
  • app.businessPath = path.resolve(app.baseDir, './app')
• 初始化环境：app.env = env()
• 按顺序加载：
  • middleware → router-schema → controller → service → config → extend → plugin
  • 以及 app/middleware.js（若存在）
• 注册路由与兜底重定向
• 启动服务：
  • PORT = process.env.PORT || 8080
  • HOST = process.env.HOST || "0.0.0.0"

🌈 Example Controller / Service

• Service 示例：app/service/user/user-info.js

module.exports = (app) => {
  return {
    async getUserById(id) {
      // 你可以在这里使用 app.plugins.mysql 等
      return { id, name: 'Hashan' };
    },
  };
};

• Controller 示例：app/controller/user/user-info.js

module.exports = (app) =>
  class UserInfoController {
    async detail(ctx) {
      const { id } = ctx.query;
      ctx.body = await app.service.user.userInfo.getUserById(id);
    }
  };

• Router 示例：app/router/user.js

module.exports = (app, router) => {
  router.get('/api/user/detail', async (ctx) => {
    await app.controller.user.userInfo.detail(ctx);
  });
};

💡 Best Practices

• 使用 小写 + 中划线 的文件名 / 目录名，让自动驼峰映射更清晰。
• 把所有外部资源（数据库 / Redis / MQ 等）封装成 Plugin，通过 config/plugin.js 管理。
• 对外只暴露一个 start()，其余全部通过 app 上下文访问，形成统一的核心运行时。

📦 License

ISC © Hashan