跳到主要内容
版本：2.0.0

Session

Session 在计算机中，尤其是在网络应用中，称为“会话控制”。Session 对象存储特定用户会话所需的属性及配置信息。这样，当用户在应用程序的 Web 页之间跳转时，存储在 Session 对象中的变量将不会丢失，而是在整个用户会话中一直存在下去。当用户请求来自应用程序的 Web 页时，如果该用户还没有会话，则 Web 服务器将自动创建一个 Session 对象。当会话过期或被放弃后，服务器将终止该会话。

在 @midwayjs/web 使用​

框架内置了 Session 插件，给我们提供了 ctx.session 来访问或者修改当前用户 Session 。

比如 Controller 中。

// src/controller/home.ts

import { Controller, Get, Provide, Inject } from '@midwayjs/decorator';
import { Context } from 'egg';

@Provide()
@Controller('/')
export class HomeController {
  @Inject()
  ctx: Context;

  @Get('/')
  async home() {
    // 获取 Session 上的内容
    const userId = this.ctx.session.userId;
    // ...

    // 修改 Session 的值
    this.ctx.session.visited = this.ctx.session.visited ? this.ctx.session.visited + 1 : 1;
  }
}

Session 的使用方法非常直观，直接读取它或者修改它就可以了，如果要删除它，直接将它赋值为 null：

ctx.session = null;

需要 特别注意 的是：设置 session 属性时需要避免以下几种情况（会造成字段丢失，详见koa-session源码）

  • 不要以 _ 开头
  • 不能为 isNew
// ❌ 错误的用法
ctx.session._visited = 1; //    --> 该字段会在下一次请求时丢失
ctx.session.isNew = 'HeHe'; //    --> 为内部关键字, 不应该去更改

// ✔️ 正确的用法
ctx.session.visited = 1; //   -->  此处没有问题

Session 的实现是基于 Cookie 的，默认配置下，用户 Session 的内容加密后直接存储在 Cookie 中的一个字段中，用户每次请求我们网站的时候都会带上这个 Cookie，我们在服务端解密后使用。Session 的默认配置如下：

export const session = {
  key: 'EGG_SESS',
  maxAge: 24 * 3600 * 1000, // 1 天
  httpOnly: true,
  encrypt: true,
};

可以看到这些参数除了 key 都是 Cookie 的参数，key 代表了存储 Session 的 Cookie 键值对的 key 是什么。在默认的配置下，存放 Session 的 Cookie 将会加密存储、不可被前端 js 访问，这样可以保证用户的 Session 是安全的。

Session 默认存放在 Cookie 中，如需放在其他存储中，具体可以查阅 Cookie 与 Session。

在 @midwayjs/koa 使用​

koa 原生功能只提供了 Cookie 的操作，但是没有提供 Session 操作。Session 就只用自己实现或者通过第三方中间件实现。

常用的 koa session 中间件有 koa-session。koa-session 默认基于 cookie 来实现 Session 数据存储，同时也支持其他存储的扩展。

首先需要安装中间件。

$ npm install koa-session --save

在启动时加载该中间件，示例如下：

// configuration.ts

import { Configuration, App } from '@midwayjs/decorator';
import { Application } from '@midwayjs/koa';
import * as session from 'koa-session';

@Configuration()
export class AutoConfiguration {
  @App()
  app: Application;

  async onReady() {
    this.app.use(
      session(
        {
          key: 'koa.sess', // cookie key
          maxAge: 24 * 3600 * 1000, // 1天
        },
        this.app
      )
    );
  }
}

这里的配置也可以放到 config 中，然后使用 @Config 装饰器注入。

这里中间件的更多选项可以参考 koa-session 文档。

之后就可以在其他地方使用了，比如：

// src/controller/home.ts

import { Controller, Get, Provide, Inject } from '@midwayjs/decorator';
import { Context } from '@midwayjs/koa';

@Provide()
@Controller('/')
export class HomeController {
  @Inject()
  ctx: Context;

  @Get('/')
  async home() {
    this.ctx.session.visits = this.ctx.session.visits ? this.ctx.session.visits + 1 : 1;
  }
}

也可以使用 @Session 装饰器获取 Session。

// src/controller/home.ts

import { Controller, Get, Provide, Inject, Session, ALL } from '@midwayjs/decorator';
import { Context } from '@midwayjs/koa';

@Provide()
@Controller('/')
export class HomeController {
  @Inject()
  ctx: Context;

  @Get('/')
  async home(@Session() visits = 1) {
    this.req.session.visits = session.visits = visits + 1;
  }
}

或者直接获取整个 Session。

// src/controller/home.ts

import { Controller, Get, Provide, Session, ALL } from '@midwayjs/decorator';

@Provide()
@Controller('/')
export class HomeController {
  @Get('/')
  async home(@Session(ALL) session) {
    session.visits = session.visits ? session.visits + 1 : 1;
  }
}

如需使用不同的存储，可以使用类似的 generic-session 来替换该中间件。

在 @midwayjs/express 使用​

首先安装依赖。

$ npm i express-session
$ npm i -D @types/express-session

加到中间件中。

// configuration.ts

import { Configuration, App } from '@midwayjs/decorator';
import { Application } from '@midwayjs/express';
import * as session from 'express-session';

@Configuration()
export class AutoConfiguration {
  @App()
  app: Application;

  async onReady() {
    this.app.use(
      session({
        secret: 'my-secret',
        resave: false,
        saveUninitialized: false,
      })
    );
  }
}

secret 用于对 sessionId cookie 进行加密。它可以是字符串，也可以是多个秘钥字符串组成的数组。如果提供了数组，则使用第一个字符串进行签名，而在验证请求中的签名时会循环所有的加密串。

这个秘钥最好是随机的一组字符。

通过获取 req 对象设置获取 Session 中的值。

// src/controller/home.ts

import { Controller, Get, Provide, Inject } from '@midwayjs/decorator';
import { Context } from '@midwayjs/express';
import { Request } from 'express';

@Provide()
@Controller('/')
export class HomeController {
  @Inject()
  req: Request;

  @Get('/')
  async home() {
    this.req.session.visits = this.req.session.visits ? this.req.session.visits + 1 : 1;
  }
}

也可以使用 @Session 装饰器获取 Session。

// src/controller/home.ts

import { Controller, Get, Provide, Inject, Session, ALL } from '@midwayjs/decorator';
import { Context } from '@midwayjs/express';
import { Request } from 'express';

@Provide()
@Controller('/')
export class HomeController {
  @Inject()
  req: Request;

  @Get('/')
  async home(@Session() visits = 1) {
    this.req.session.visits = session.visits = visits + 1;
  }
}

或者直接获取整个 Session。

// src/controller/home.ts

import { Controller, Get, Provide, Session, ALL } from '@midwayjs/decorator';
import { Context } from '@midwayjs/express';

@Provide()
@Controller('/')
export class HomeController {
  @Get('/')
  async home(@Session(ALL) session) {
    session.visits = session.visits ? session.visits + 1 : 1;
  }
}

在 Serverless 场景使用​

Serverless 场景有与弹性的存在，没有维护 Session 的必要性，最多只能使用基于 Cookie 的 Session。