sky_ssd

Sky SSD (Skynet Server-Side Development)

一个基于 Koa.js 的企业级 Node.js Web 开发框架，提供完整的后端服务解决方案。

特性

• 快速开发 - 基于约定优于配置的理念，快速构建 RESTful API
• 安全认证 - 内置 JWT 认证和权限控制系统
• 数据库集成 - PostgreSQL 数据库支持，自动 CRUD 操作
• API 文档 - 自动生成 Swagger/OpenAPI 文档
• 日志系统 - 完整的访问日志、错误日志和审计日志
• 文件存储 - MinIO 对象存储集成
• 国密算法 - SM2/SM3/SM4 加密算法支持
• 高性能 - 连接池管理、超时控制、错误处理

安装

npm install sky_ssd
# 或
yarn add sky_ssd

快速开始

1. 创建应用

const Koa = require('koa');
const { init } = require('sky_ssd');

const app = new Koa();

// 初始化框架
init(app);

app.listen(3000, () => {
  console.log('服务器启动在端口 3000');
});

2. 创建配置文件

在项目根目录创建 ssd_config.js：

module.exports = {
  // 数据库配置
  dbCfg: {
    host: 'localhost',
    port: 5432,
    database: 'your_database',
    user: 'your_username',
    password: 'your_password',
    max: 20, // 连接池最大连接数
    idleTimeoutMillis: 30000,
    connectionTimeoutMillis: 2000,
  },
  
  // JWT 配置
  jwtCfg: {
    pub_secret: () => Buffer.from(process.env.JWT_PUBLIC_KEY, 'base64'),
    pri_secret: () => Buffer.from(process.env.JWT_PRIVATE_KEY, 'base64')
  },
  
  // API 信息
  apiInfo: {
    title: "我的 API",
    description: "API 接口文档",
    version: "1.0.0"
  },
  
  // 跨域配置
  cors: {
    origin: '*',
    allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowHeaders: ['Content-Type', 'Authorization']
  }
};

3. 创建 API 路由

在 routes 目录下创建路由文件：

// routes/user.js
module.exports = {
  // 路由格式: "HTTP方法 路径 --描述"
  'GET /users --获取用户列表': async (ctx) => {
    const users = await ctx.db({
      text: 'SELECT * FROM users',
      rdt: r => r.rows
    });
    ctx.resp('获取成功', users);
  },
  
  'POST /users --创建用户': async (ctx) => {
    const { name, email } = ctx.request.body;
    const result = await ctx.db({
      text: 'INSERT INTO users(name, email) VALUES($1, $2) RETURNING *',
      values: [name, email]
    });
    ctx.resp('创建成功', result.rows[0]);
  }
};

4. 创建 CRUD 配置

在 sqls 目录下创建 CRUD 配置：

// sqls/user.js
const { csql, rsqls, usql, dsql } = require('sky_ssd').sqlHelp;

module.exports = {
  // 查询所有用户
  list: rsqls.t('users'),
  
  // 根据ID查询用户
  detail: rsqls.tfk('users'),
  
  // 创建用户
  create: csql('users', '', 'id'),
  
  // 更新用户
  update: usql('users'),
  
  // 删除用户
  delete: dsql('users'),
  
  $desc: '用户管理'
};

核心概念

路由约定

路由文件使用特定的命名约定：

module.exports = {
  // 格式: "[超时时间:]HTTP方法 路径 --描述"
  '10:POST /api/upload --文件上传': handler,
  'GET /api/users --用户列表': handler,
  'PUT /api/users/:id --更新用户': handler
};

CRUD 操作

框架提供了丰富的 SQL 辅助函数：

• csql(tableName, timeFields, returnId) - 创建插入语句
• usql(tableName, primaryKey, excludeFields) - 创建更新语句
• dsql(tableName, primaryKey) - 创建删除语句
• rsqls.t(tableName) - 查询全表
• rsqls.tfk(tableName, fields, key) - 根据主键查询

认证和权限

// 登录
POST /login
{
  "id": "username",
  "password": "password"
}

// 受保护的路由会自动验证 JWT token
// 在请求头中添加: Authorization: Bearer <token>

配置选项

详细配置选项请参考 src/defCfg.js 文件。主要配置包括：

• dbCfg - 数据库连接配置
• jwtCfg - JWT 认证配置
• cors - 跨域配置
• bodyParse - 请求体解析配置
• logCfg - 日志配置
• minioCfg - MinIO 文件存储配置

API 文档

启动应用后，访问以下地址查看 API 文档：

• Swagger UI: http://localhost:3000/swagger
• OpenAPI JSON: http://localhost:3000/openapi

工具函数

框架提供了丰富的工具函数：

const { util } = require('sky_ssd');

// 文件扫描
const files = util.fss('./directory');

// 超时控制
const timeoutFn = util.ato(5, asyncFunction);

// Base64 转换
util.base64ToImg('./image.png', base64Data);
const base64 = util.imgToBase64('./image.png');

// 随机码生成
const code = util.getCode(6);

日志

框架内置完整的日志系统：

// 在路由处理函数中使用
ctx.logs.info('信息日志');
ctx.logs.error('错误日志');
ctx.logs.debug('调试日志');
ctx.logs.audit('操作审计', { userId: 123 });

安全特性

• JWT 令牌认证
• 资源权限控制
• 请求超时保护
• 错误信息脱敏
• 国密算法支持

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

支持

如有问题，请联系：skynet901