mm_session

中文 | English

概述

mm_session 是一个专为 Koa.js 框架设计的轻量级 session 管理中间件。它提供了简单易用的 session 管理功能，支持自定义存储后端，适用于各种规模的 Web 应用。

这是超级美眉session函数模块，用于web服务端session缓存。

特性

• ✅ Koa 中间件标准 - 符合 app.use(session({ key: 'test_session', max_age: 3600 })) 使用方式
• ✅ 存储抽象层 - 支持自定义存储后端
• ✅ 自动 session 管理 - 自动创建、保存、销毁 session
• ✅ Cookie 自动处理 - 自动设置和读取 session cookie
• ✅ 安全 session ID - 基于 IP + 时间戳 + AES 加密生成
• ✅ 异步支持 - 完整的 async/await 支持
• ✅ 轻量级 - 无冗余依赖，代码简洁
• ✅ 生产就绪 - 经过充分测试，稳定可靠

安装

npm install mm_session

快速开始

基本用法

const Koa = require('koa');
const { session } = require('mm_session');

const app = new Koa();

// 注册中间件
app.use(session({
  key: 'my_session',      // cookie 名称
  max_age: 3600          // session 过期时间（秒）
}));

// 业务路由
app.use(async (ctx) => {
  // 设置 session 数据
  if (!ctx.session.user_id) {
    ctx.session.user_id = 123;
    ctx.session.username = 'test_user';
  }
  
  // 读取 session 数据
  ctx.body = {
    user_id: ctx.session.user_id,
    username: ctx.session.username
  };
});

app.listen(3000);

高级配置

const { Session, Store } = require('mm_session');

// 自定义配置
const session = new Session({
  key: 'app_session',           // cookie 键名
  max_age: 7200,               // 过期时间：2小时
  http_only: true,             // 仅 HTTP 访问
  secure: process.env.NODE_ENV === 'production', // 生产环境 HTTPS
  same_site: 'strict'          // 同站策略
});

// 自定义存储（可选）
const customStore = new Store('custom_prefix');
session.init(customStore);

API 文档

Session 类

构造函数

new Session(config)

参数:

• config (Object) - 配置对象
  • key (String) - session cookie 名称，默认: 'mm:uuid'
  • max_age (Number) - session 过期时间（秒）
  • 其他 cookie 配置选项

方法

middleware()

返回 Koa 中间件函数。

app.use(session.middleware());

init(store)

初始化自定义存储后端。

session.init(new CustomStore());

Store 类

存储抽象类，支持自定义存储实现。

const { Store } = require('mm_session');
const store = new Store('prefix_');

配置选项

Session 配置

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | key | String | 'mm:uuid' | session cookie 名称 | | max_age | Number | - | session 过期时间（秒） | | http_only | Boolean | true | 仅 HTTP 访问 | | secure | Boolean | false | 仅 HTTPS 传输 | | same_site | String | 'lax' | 同站策略 |

Cookie 配置

支持所有 cookie 库的配置选项。

存储后端

默认存储

默认使用 mm_cachebase 作为存储后端，支持内存和文件持久化。

自定义存储

可以实现自定义存储类，只需实现以下接口：

class CustomStore {
  async get(sessionId) {}
  async set(sessionData, options, ctx) {}
  async destroy(sessionId, ctx) {}
  async getID(ctx) {}
}

示例应用

用户登录系统

const session = new Session({
  key: 'user_session',
  max_age: 86400 // 24小时
});

app.use(session.middleware());

// 登录路由
app.use(async (ctx, next) => {
  if (ctx.path === '/login' && ctx.method === 'POST') {
    const { username, password } = ctx.request.body;
    
    // 验证用户（示例）
    if (username === 'admin' && password === 'password') {
      ctx.session.user = {
        id: 1,
        username: 'admin',
        role: 'administrator'
      };
      ctx.body = { success: true };
    } else {
      ctx.body = { success: false, error: '认证失败' };
    }
  } else {
    await next();
  }
});

// 需要认证的路由
app.use(async (ctx, next) => {
  if (!ctx.session.user) {
    ctx.status = 401;
    ctx.body = { error: '请先登录' };
    return;
  }
  await next();
});

测试

# 运行测试
npm test

# 或直接运行
node test.js

开发

代码规范

项目使用 ESLint 进行代码规范检查：

# 检查代码规范
npx eslint lib/session.js

# 自动修复
npx eslint lib/session.js --fix

项目结构

mm_session/
├── lib/
│   ├── session.js     # Session 类实现
│   └── store.js       # Store 类实现
├── index.js           # 模块入口
├── test.js            # 测试文件
├── eslint.config.js   # ESLint 配置
└── package.json       # 项目配置

贡献

欢迎贡献！请随时提交 Issue 和 Pull Request。

开发环境设置

1. 克隆仓库：

git clone https://gitee.com/qiuwenwu91/mm_session.git
cd mm_session

2. 安装依赖：

npm install

3. 运行测试：

npm test

许可证

ISC License

版权所有 (c) 2024 邱文武

特此免费授予任何获得本软件副本和相关文档文件（以下简称"软件"）的人不受限制地处理本软件的权限，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售本软件的副本，以及允许提供本软件的人员这样做，但须符合以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中。

作者

邱文武

更新日志

v1.5.3

• 当前稳定版本

v1.5.1

• 修复 session 保存逻辑
• 优化 cookie 设置机制
• 改进测试用例

v1.5.0

• 重构为类+原型函数模式
• 符合 Koa 中间件标准使用方式
• 增强代码可维护性

错误报告

如果您遇到任何错误或有功能请求，请在 Git 仓库 上提交 Issue。

相关项目

• mm_cache - 缓存库（依赖项）
• mm_eslint - ESLint 配置（开发依赖项）

支持

如需支持和问题解答，请查阅文档或在项目仓库中创建 Issue。