xlt-token/
├── src/
│ ├── auth/ # 认证核心逻辑
│ │ ├── stp-logic.ts # Token 生命周期管理（登录、登出、踢人、续签）
│ │ └── stp-util.ts # 静态门面 StpUtil
│ ├── core/
│ │ └── xlt-token-config.ts # 配置定义
│ ├── perm/ # 权限 / 角色校验
│ │ ├── stp-interface.ts # 业务接口（权限列表、角色列表）
│ │ ├── stp-perm-logic.ts # 校验引擎（AND/OR + 通配符）
│ │ └── perm-pattern-match.ts # 通配符匹配引擎
│ ├── session/
│ │ └── xlt-session.ts # 会话管理
│ ├── guards/ # 守卫层
│ │ ├── xlt-token.guard.ts # 全局 Token 守卫
│ │ └── xlt-abstract-login.guard.ts # 可扩展登录守卫基类
│ ├── decorators/ # 声明式装饰器
│ │ ├── xlt-ignore.decorator.ts
│ │ ├── xlt-check-login.decorator.ts
│ │ ├── login-id.decorator.ts
│ │ ├── token-value.decorator.ts
│ │ ├── xlt-check-permission.decorator.ts
│ │ └── xlt-check-role.decorator.ts
│ ├── store/ # 存储后端
│ │ ├── xlt-token-store.interface.ts # 存储接口
│ │ ├── memory-store.ts # 内存存储（开发环境）
│ │ └── redis-store.ts # Redis 存储（生产环境）
│ ├── token/ # Token 生成策略
│ │ ├── token-strategy.interface.ts
│ │ └── uuid-strategy.ts
│ ├── exceptions/ # 异常定义
│ │ ├── not-login.exception.ts
│ │ ├── not-permission.exception.ts
│ │ └── not-role.exception.ts
│ ├── const/ # 常量定义
│ │ └── index.ts
│ ├── index.ts # 包入口
│ └── xlt-token.module.ts # NestJS 模块入口
├── test/ # 测试用例
│ ├── unit/ # 158 个单元测试
│ └── e2e/ # 37 个 E2E 测试
├── docs/ # 📖 在线文档
├── package.json
└── tsconfig.json

import { StpUtil } from 'xlt-token';

// 无需注入，直接调用
const token = await StpUtil.login(userId);
const loginId = await StpUtil.getLoginId(req);

canActivate
 ├─ requiresLogin(ctx) // 可重写：替换元数据策略
 │ └─ 否 → 直接放行
 ├─ stpLogic.checkLogin(request)
 ├─ !ok → onAuthFail(result, request) // 可重写
 │ throw NotLoginException
 └─ ok → request.stpLoginId / stpToken 赋值
     → onAuthSuccess(result, request) // 可重写：业务会话加载

// AND 模式：全部满足
@XltCheckPermission(['order:read', 'order:write'], { mode: XltMode.AND })

// OR 模式：任一满足
@XltCheckRole(['admin', 'super'], { mode: XltMode.OR })

// 通配符匹配
@XltCheckPermission('order:*')

pnpm add xlt-token
# 或
npm install xlt-token
# 或
yarn add xlt-token

pnpm add redis

// app.module.ts
import { Module } from '@nestjs/common';
import { XltTokenModule } from 'xlt-token';

@Module({
  imports: [
    XltTokenModule.forRoot({
      isGlobal: true,
      config: {
        tokenName: 'authorization',
        timeout: 2592000, // 30 天
        tokenStyle: 'uuid',
        tokenPrefix: 'Bearer ',
      },
    }),
  ],
})
export class AppModule {}

// auth.service.ts
import { Injectable } from '@nestjs/common';
import { StpLogic } from 'xlt-token';

@Injectable()
export class AuthService {
  constructor(private readonly stpLogic: StpLogic) {}

  async login(userId: string) {
    const token = await this.stpLogic.login(userId);
    return { token };
  }
}

// user.controller.ts
import { Controller, Get, Post } from '@nestjs/common';
import { XltIgnore, LoginId } from 'xlt-token';

@Controller('user')
export class UserController {
  @XltIgnore() // 忽略登录校验
  @Post('login')
  async login() {
    // 登录逻辑
  }

  @Get('profile')
  async getProfile(@LoginId() loginId: string) {
    return { userId: loginId };
  }
}

// app.module.ts
import { APP_GUARD } from '@nestjs/core';
import { XltTokenGuard } from 'xlt-token';

@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: XltTokenGuard,
    },
  ],
})
export class AppModule {}

// stp.service.ts — 实现 StpInterface 业务接口
import { Injectable } from '@nestjs/common';
import { StpInterface } from 'xlt-token';

@Injectable()
export class StpService implements StpInterface {
  async getPermissionList(loginId: string): Promise<string[]> {
    // 从数据库 / 缓存读取
    return ['user:read', 'user:write', 'order:*'];
  }

  async getRoleList(loginId: string): Promise<string[]> {
    return ['admin'];
  }
}

// 在 Controller 上使用
import { XltCheckPermission, XltCheckRole, XltMode } from 'xlt-token';

@Controller('order')
export class OrderController {
  @XltCheckPermission('order:read') // 单一权限
  @Get()
  list() {}

  @XltCheckPermission(['order:read', 'order:write'],
    { mode: XltMode.AND }) // 全部满足
  @Post()
  create() {}

  @XltCheckRole(['admin', 'super'],
    { mode: XltMode.OR }) // 任一满足
  @Delete(':id')
  remove() {}

  @XltCheckPermission('order:*') // 通配符匹配
  @Patch(':id')
  update() {}
}

import { StpUtil } from 'xlt-token';

// 写入
const session = StpUtil.getSession(loginId);
await session.set('nickname', 'xlt');
await session.set('lastLoginIp', '127.0.0.1');

// 读取
const nickname = await session.get<string>('nickname');

// 其他方法
await session.has('nickname'); // boolean
await session.remove('nickname');
const keys = await session.keys(); // string[]
await session.clear();

const record = await StpUtil.getOfflineReason(token);
// { reason: 'KICK_OUT' | 'BE_REPLACED', time: 1714112400000 }

import { NotLoginException, NotLoginType } from 'xlt-token';

try {
  await stpLogic.checkLogin(req);
} catch (e) {
  if (e instanceof NotLoginException) {
    switch (e.message) {
      case NotLoginType.NOT_TOKEN: // 请求中没 token
        break;
      case NotLoginType.INVALID_TOKEN: // token 在服务端找不到
        break;
      case NotLoginType.TOKEN_TIMEOUT: // token 已过期
        break;
      case NotLoginType.TOKEN_FREEZE: // 临时活跃过期
        break;
      case NotLoginType.BE_REPLACED: // 被顶号
        break;
      case NotLoginType.KICK_OUT: // 被踢下线
        break;
    }
  }
}

import { Module } from '@nestjs/common';
import { XltTokenModule, RedisStore, XLT_REDIS_CLIENT } from 'xlt-token';
import { createClient } from 'redis';

@Module({
  imports: [
    XltTokenModule.forRoot({
      store: { useClass: RedisStore },
      providers: [
        {
          provide: XLT_REDIS_CLIENT,
          useFactory: async () => {
            const client = createClient({
              url: 'redis://localhost:6379',
            });
            await client.connect();
            return client;
          },
        },
      ],
    }),
  ],
})
export class AppModule {}

import { XltTokenStore } from 'xlt-token';

export class CustomStore implements XltTokenStore {
  async get(key: string): Promise<string | null> { /* ... */ }
  async set(key: string, value: string, timeoutSec: number): Promise<void> { /* ... */ }
  async delete(key: string): Promise<void> { /* ... */ }
  async has(key: string): Promise<boolean> { /* ... */ }
  async update(key: string, value: string): Promise<void> { /* ... */ }
  async updateTimeout(key: string, timeoutSec: number): Promise<void> { /* ... */ }
  async getTimeout(key: string): Promise<number> { /* ... */ }
}