Back to Details

sa-token-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sa-Token 集成扩展

Sa-Token Integration Extensions

基于 
sa-token-doc/plugin/
集成类文档。
Based on the integration documentation in 
sa-token-doc/plugin/
.

适用场景

Applicable Scenarios

当用户需要以下场景时，激活此技能：
  • JWT无状态认证 — 将登录信息编码到Token中，减少Redis查询，适合高并发场景
  • 分布式Session共享 — 多实例部署时需要共享会话数据
  • Redis缓存隔离 — 将Sa-Token的Redis与业务Redis物理分开
  • Service层注解鉴权 — 在Service层（非Controller）使用@SaCheckLogin等注解
  • 快速搭建登录页面 — 开发环境或内管系统零代码登录页
  • 模板引擎鉴权标签 — Thymeleaf/Freemarker页面中控制按钮显隐
Activate this skill when the user needs any of the following:
  • JWT stateless authentication — Encode login information into the Token to reduce Redis queries, making it suitable for high-concurrency scenarios
  • Distributed Session sharing — Share session data across multiple instances in a distributed deployment
  • Redis cache isolation — Physically separate Sa-Token Redis data from the business Redis data
  • Service-layer annotation-based authorization — Use annotations such as @SaCheckLogin at the Service layer instead of the Controller layer
  • Rapid login page development — Build a zero-code login page for development environments or internal administration systems
  • Template engine authorization tags — Control button visibility in Thymeleaf/Freemarker pages

Workflow

Workflow

Step 1. 确定集成需求 — 选择JWT/Redis/AOP/模板等模块 Step 2. 引入依赖 — 添加对应Maven/Gradle依赖 Step 3. 配置参数 — 配置jwt-secret-key/Redis连接/Alone-Redis等 Step 4. 注入实现 — 注入StpLogic、注册过滤器、配置模板引擎 Step 5. 验证测试 — 确认集成生效，测试核心功能是否正常
Step 1. Identify integration requirements — Select the JWT, Redis, AOP, template, or other required modules Step 2. Add dependencies — Add the corresponding Maven/Gradle dependencies Step 3. Configure parameters — Configure jwt-secret-key, Redis connections, Alone-Redis, and other settings Step 4. Wire up implementations — Inject StpLogic, register filters, and configure the template engine Step 5. Verify the integration — Confirm that the integration is effective and test whether the core functionality works correctly

Capability Boundaries

Capability Boundaries

✅ Strong Suits

✅ Strong Suits

  1. JWT集成 — Simple/Mixin/Stateless三种模式选择
  2. Redis持久化 — JDK序列化/JSON序列化两种方式
  3. Alone-Redis独立Redis — 认证缓存与业务缓存物理隔离
  4. AOP注解鉴权 — 在Service层使用@SaCheckLogin等注解
  5. SpEL表达式 — @SaCheckEL使用Spring表达式
  6. Quick-Login快速登录 — 零代码注入登录页面
  7. JSON序列化扩展 — Jackson/Fastjson/Fastjson2/Snack3/Snack4
  8. 模板引擎集成 — Thymeleaf/Freemarker自定义标签
  9. RPC集成 — Dubbo/Dubbo3/gRPC上下文传播
  1. JWT integration — Choose among the Simple, Mixin, and Stateless modes
  2. Redis persistence — Use either JDK serialization or JSON serialization
  3. Alone-Redis standalone Redis — Physically isolate authentication and business caches
  4. AOP annotation-based authorization — Use annotations such as @SaCheckLogin at the Service layer
  5. SpEL expressions — Use Spring expressions with @SaCheckEL
  6. Quick-Login rapid login — Inject a zero-code login page
  7. JSON serialization extensions — Jackson/Fastjson/Fastjson2/Snack3/Snack4
  8. Template engine integration — Custom tags for Thymeleaf/Freemarker
  9. RPC integration — Context propagation for Dubbo/Dubbo3/gRPC

⚠️ Requirements

⚠️ Requirements

  1. JWT需要配置 
    jwt-secret-key
  2. Redis需要配置 
    spring.redis
    连接信息
  3. AOP注解与拦截器注解不能同时使用
  1. JWT requires the 
    jwt-secret-key
    configuration
  2. Redis requires the 
    spring.redis
    connection information
  3. AOP annotations and interceptor annotations cannot be used together

❌ Out of Scope

❌ Out of Scope

  1. 基础登录/权限/注解鉴权 → sa-token
  2. SSO → sa-token-sso
  3. OAuth2.0 → sa-token-oauth2
  4. 微服务鉴权 → sa-token-micro
  1. Basic login, permissions, and annotation-based authorization → sa-token
  2. SSO → sa-token-sso
  3. OAuth2.0 → sa-token-oauth2
  4. Microservice authentication and authorization → sa-token-micro

参考文档

Reference Documentation

主题文件来源
JWT三模式(Simple/Mixin/Stateless)references/jwt-extend.mdGitHub
Redis持久化+Alone-Redisreferences/dao-extend.mddao-extend、integ-redis
TopicFileSource
Three JWT modes (Simple/Mixin/Stateless)references/jwt-extend.mdGitHub
Redis persistence and Alone-Redisreferences/dao-extend.mddao-extend, integ-redis

FAQ

FAQ

Q: JWT三种模式怎么选？ A: Simple模式推荐（功能完整：踢人、封禁、会话管理都支持）。需要无状态选Stateless（但踢人/封禁不可用）。Mixin介于两者之间。
Q: Redis两种序列化方式选哪个？ A: 推荐RedisTemplate JSON序列化（数据可读，方便排查）。JDK序列化兼容性更好但数据是乱码。
Q: Alone-Redis和普通Redis有什么区别？ A: Alone-Redis使用独立的Redis连接和数据库，与业务Redis完全隔离，保证认证缓存不受业务影响。
Q: AOP注解鉴权和拦截器鉴权能同时用吗？ A: 不能同时使用。AOP用于Service层，拦截器用于Controller层，选择一种即可。
Q: Quick-Login适合生产环境吗？ A: 适合小系统或内部管理系统。生产环境建议自定义登录页面。
Q: 模板引擎标签支持哪些功能？ A: 支持 
sa:login
（登录校验）、
sa:hasRole
（角色判断）、
sa:hasPermission
（权限判断）等标签。
Q: How do I choose among the three JWT modes? A: The Simple mode is recommended because it provides a complete feature set, including force logout, banning, and session management. Choose Stateless when true stateless operation is required, although force logout and banning are unavailable. Mixin falls between the two.
Q: Which Redis serialization method should I use? A: RedisTemplate-based JSON serialization is recommended because the data is human-readable and easier to troubleshoot. JDK serialization offers better compatibility, but the data is not human-readable.
Q: What is the difference between Alone-Redis and regular Redis? A: Alone-Redis uses an independent Redis connection and database that is completely isolated from the business Redis, ensuring that business traffic does not affect the authentication cache.
Q: Can AOP annotation-based authorization and interceptor-based authorization be used together? A: No. AOP is intended for the Service layer, while interceptors are intended for the Controller layer. Choose one approach.
Q: Is Quick-Login suitable for production environments? A: It is suitable for small systems or internal administration systems. For production environments, a custom login page is recommended.
Q: What functions are supported by the template engine tags? A: Tags such as 
sa:login
for login verification, 
sa:hasRole
for role checks, and 
sa:hasPermission
for permission checks are supported.

Gotchas

Gotchas

  1. Simple模式 
    is-share
    恒等于false     — 与Extra数据不兼容，无法共用token
  2. Mixin模式 
    is-concurrent
    必须为true     — 否则踢人下线API不可用
  3. JWT集成后Token变为JWT格式 — 不再是uuid格式，内容可解码查看
  4. Alone-Redis有独立的配置前缀 
    sa-token-alone-redis
     — 不是 
    spring.redis
  5. Redis JSON序列化后Session数据在Redis中可读 — 可在Redis客户端中直接查看
  6. AOP注解和拦截器注解不能混用 — 选了AOP就不能再用拦截器
  7. Quick-Login默认账号密码 sa/123456 — 生产环境务必修改
  8. Dubbo集成自动处理上下文传播 — 无需额外代码，引入依赖即可
  1. is-share
    is always false in Simple mode     — It is incompatible with Extra data, and tokens cannot be shared
  2. is-concurrent
    must be true in Mixin mode     — Otherwise, the force-logout API is unavailable
  3. Tokens use the JWT format after JWT integration — They are no longer UUID-formatted, and their contents can be decoded and viewed
  4. Alone-Redis uses the independent configuration prefix 
    sa-token-alone-redis
     — It does not use 
    spring.redis
  5. Session data is readable in Redis after JSON serialization — It can be viewed directly in a Redis client
  6. AOP annotations and interceptor annotations cannot be mixed — Choosing AOP means interceptor-based annotations cannot also be used
  7. The default Quick-Login credentials are sa/123456 — They must be changed in production environments
  8. Dubbo integration automatically handles context propagation — No additional code is required; simply add the dependency

Data Privacy

Data Privacy

本技能不收集、存储或传输任何用户数据。所有代码示例仅供本地开发参考。
This skill does not collect, store, or transmit any user data. All code examples are provided for local development reference only.