mirror of synced 2026-08-31 15:44:35 +00:00

Files

T

click33 c3a4834da7 docs: README 角标补充 JDK 8~25 支持范围

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-28 17:45:46 +08:00

40 KiB

Raw Permalink Blame History

Sa-Token v1.46.0

✨ Бесплатная универсальная платформа аутентификации Java-разрешений с открытым исходным кодом, делающая аутентификацию простой и элегантной!

Онлайн-документация: https://sa-token.com | Отправка запроса

📝 Предисловие:

Оглядываясь назад на начало 2020 года, когда я представил первую строку кода для Sa-Token, я понимаю, что Java на рынке в то время не хватало не только простой и удобной в использовании инфраструктуры аутентификации, но и целостного набора четких и самосогласованных идей проектирования архитектуры разрешений.

Поэтому в последние несколько лет я посвятил много времени написанию документации Sa-Token. Почти каждая глава, каждое предложение и каждое слово были неоднократно переработаны и тщательно отшлифованы, чтобы добиться максимально ясного, лаконичного и легкого для понимания выражения. Внимательно прочитайте документацию, и вы изучите не только саму структуру Sa-Token, но и лучшие практики проектирования аутентификации и авторизации в большинстве сценариев.

🛠️ Введение Sa-Token

Sa-Token — это облегченная платформа аутентификации разрешений Java, которая в настоящее время имеет пять основных модулей: аутентификация входа, аутентификация разрешений, единый вход, OAuth2.0 и аутентификация микросервиса.

Вы всё ещё пишете эти функции вручную? Stop, пусть поможет Sa-Token!

Чтобы использовать Sa-Token в проекте SpringBoot, вам нужно всего лишь ввести зависимости в pom.xml:

<!-- Аутентификация органа Sa-Token, онлайн-документ: https://sa-token.com -->
<dependency>
	<groupId>cn.dev33</groupId>
	<artifactId>sa-token-spring-boot-starter</artifactId>
	<version>1.46.0</version>
</dependency>

Помимо поддержки SpringBoot2 и Sa-Token, он также предоставляет пакеты интеграции для распространенных веб-платформ, таких как SpringBoot3/4, Solon и JFinal, что делает его по-настоящему пригодным для использования прямо из коробки.

Простой пример отображения: (нажмите, чтобы развернуть/свернуть)

Sa-Token стремится завершить часть системы аутентификации разрешений простым и элегантным способом. Если взять в качестве примера аутентификацию при входе, вам нужно всего лишь:

// Вход в сеанс, параметр заполняется идентификатором учетной записи пользователя, вошедшего в систему.
StpUtil.login(10001);

Нет необходимости реализовывать какой-либо интерфейс или создавать какой-либо файл конфигурации. Вам нужно только вызвать этот статический код для завершения аутентификации входа в сеанс.

Если интерфейс требует входа в систему перед доступом к нему, нам нужно всего лишь вызвать следующий код:

// Проверьте, вошел ли текущий клиент в систему, если нет, выдайте исключение `NotLoginException`.
StpUtil.checkLogin();

В Sa-Token большинство функций можно решить одной строкой кода:

Выкидывать людей из сети:

// Отключить сеанс с идентификатором учетной записи 10077 в автономном режиме.
StpUtil.kickout(10077);

Аутентификация разрешения:

// Аутентификация аннотаций: только сеансы с разрешением `user:add` могут войти в этот метод.
@SaCheckPermission("user:add")
public String insert(SysUser user) {
    // ... 
    return "用户增加";
}

Аутентификация перехвата маршрута:

// Разделите модули по маршрутам, и разные модули имеют разную аутентификацию.
registry.addInterceptor(new SaInterceptor(handler -> {
	SaRouter.match("/user/**", r -> StpUtil.checkPermission("user"));
	SaRouter.match("/admin/**", r -> StpUtil.checkPermission("admin"));
	SaRouter.match("/goods/**", r -> StpUtil.checkPermission("goods"));
	SaRouter.match("/orders/**", r -> StpUtil.checkPermission("orders"));
	SaRouter.match("/notice/**", r -> StpUtil.checkPermission("notice"));
	// Еще модули...
})).addPathPatterns("/**");

Если вы раньше использовали Shiro или SpringSecurity, после перехода на Sa-Token вы испытаете качественный скачок.

Список основных модулей: (нажмите, чтобы развернуть/свернуть)

Аутентификация при входе - Односторонний вход, многосторонний вход, взаимоисключающий вход на одном конце, вход в систему не требуется в течение семи дней.
Аутентификация разрешений ——Аутентификация разрешений, аутентификация ролей, вторичная аутентификация сеанса.
Выключать людей из сети. Выключать людей из сети на основе идентификатора учетной записи и исключать людей из сети на основе значения токена.
Аутентификация по аннотациям — элегантно отделяет аутентификацию от бизнес-кода.
Аутентификация перехвата маршрута - На основе аутентификации перехвата маршрута можно адаптировать под RESTful-режим.
Сеанс — общий сеанс для всех концов, эксклюзивный сеанс для одного конца, настраиваемый сеанс, удобный доступ к значениям.
Расширение уровня сохранения. Redis можно интегрировать, и данные не будут потеряны после перезапуска.
Разделение внешней и внутренней части. Приложения, апплеты и другие терминалы, не поддерживающие файлы cookie, также можно легко аутентифицировать.
Настройка стиля токена — шесть встроенных стилей токенов, вы также можете настроить стратегию генерации токенов.
Режим «Запомнить меня» — адаптируйтесь к режиму [Запомнить меня] и перезапустите браузер без проверки.
Аутентификация второго уровня — Повторная аутентификация на основе входа в систему для обеспечения безопасности.
Имитация учетных записей других людей - Манипулируйте любыми данными о статусе пользователя в режиме реального времени.
Временное переключение удостоверения — Временное переключение удостоверения сеанса на другую учетную запись.
Взаимоисключающий вход с одного и того же конца - Как и в случае с QQ, мобильный телефон и компьютер находятся в сети одновременно, но вход в систему является взаимоисключающим на обоих мобильных телефонах.
Блокировка учетной записи. Блокировка входа в систему, блокировка бизнес-класса и блокировка по шкале штрафов.
Шифрование паролей. Предоставляет базовые алгоритмы шифрования, позволяющие быстро шифровать MD5, SHA1, SHA256 и AES.
Запрос сеанса. Предоставляет удобный и гибкий интерфейс запроса сеанса.
Базовая аутентификация HTTP — одна строка кода для доступа к базовой и дайджест-аутентификации Http.
Глобальный прослушиватель. Выполнение некоторых операций АОП во время ключевых операций, таких как вход пользователя в систему, выход из системы и выход из сети.
Глобальный фильтр. Удобная обработка междоменных, глобальных настроек ответа безопасности в первую очередь и других операций.
Системная аутентификация с несколькими учетными записями. Несколько учетных записей в одной системе аутентифицируются отдельно (например, таблица пользователей и таблица администраторов торгового центра).
Единый вход. Встроены три режима единого входа: тот же домен, междоменный, тот же Redis, перекрестный Redis, разделение внешнего и внутреннего интерфейса, а также могут обрабатываться другие архитектуры.
Одноточечный выход — инициируйте выход из системы в любой подсистеме, и вся система перейдет в автономный режим.
Аутентификация OAuth2.0 - Легко создавать службу OAuth2.0, поддерживающую режим openid.
Распределенный сеанс — предоставляет решение для распределенного сеанса в общем центре обработки данных.
Аутентификация микросервисного шлюза - Адаптировано для аутентификации перехвата маршрутов общих шлюзов, таких как Gateway, ShenYu, Zuul и т. д.
Аутентификация вызовов RPC - Аутентификация пересылки шлюза, аутентификация вызовов RPC, чтобы вызовы сервисов больше не оставались без защиты
Временная аутентификация по токену - Решите краткосрочную проблему авторизации по токену.
Независимый Redis - Отдельный кеш разрешений и бизнес-кеш.
Quick — быстрая аутентификация входа - Добавьте в проект страницу входа без кода.
Диалект тегов — предоставляет пакет интеграции диалекта тегов Thymeleaf и примеры интеграции Beetl.
Интеграция jwt — предоставляет три режима решений интеграции jwt и предоставляет возможности расширения параметров токена.
Передача статуса вызова RPC - Предоставляет пакеты интеграции, такие как dubbo и grpc, чтобы статус входа не терялся при вызове RPC.
Подпись параметра. Предоставляет межсистемный модуль проверки подписи вызова API для предотвращения подделки параметров и повторного запроса.
Автоматическое продление. Обеспечивает две стратегии истечения срока действия токена, которые можно гибко использовать и автоматически продлевать.
Готово - Предоставляет готовые к использованию общие пакеты интеграции с инфраструктурой, такие как SpringMVC, WebFlux, Solon и т. д.
Новейший стек технологий. Адаптируйтесь к новейшему стеку технологий: поддержка SpringBoot 3.x, jdk 17.

🍃 Единый вход

Единый вход Sa-Token разделен на три режима, которые могут удовлетворить требования аутентификации единого входа в 同域、跨域、共享Redis、跨Redis、前后端一体、前后端分离、纯 js、vue2、vue3、java 项目、非 java 项目 и других архитектурах:

Системная архитектура	Модели принятия	Введение	Ссылки на документацию
Интерфейсная часть в том же домене + серверная часть в том же домене, что и Redis	Режим 1	Общий сеанс синхронизации файлов cookie	Документ, Пример
Разные домены во внешнем интерфейсе + тот же серверный интерфейс, что и у Redis	Режим 2	Сеанс распространения перенаправления URL	Документ, Пример
Разные внешние домены + разные внутренние Redis	Режим 3	HTTP-запрос для получения сеанса	Документ, Пример

Один и тот же домен внешнего интерфейса: означает, что несколько систем могут быть развернуты под одним и тем же основным именем домена, например: c1.domain.com, c2.domain.com, c3.domain.com.
Серверная часть такая же, как у Redis. Это означает, что несколько систем могут подключаться к одному и тому же Redis и совместно использовать данные сеанса.
Если невозможно гарантировать, что интерфейсная часть находится в одном домене, а серверная часть находится в одном Redis, вы можете использовать третий режим поддержки: HTTP-запрос проверочного билета для получения сеанса.
Предоставлено: пример режима NoSdk + документ интерфейса sso-сервера, также можно подключить проекты, не относящиеся к Sa-Token, и проекты, не относящиеся к Java.
Обеспечить: множественную проверку безопасности: проверку доменного имени, проверку билета, проверку подписи параметров, эффективное предотвращение перехвата билетов, повтора запроса и других атак.
Предоставить: Большое количество практических уроков по болевым точкам: проектирование разделения внешнего и внутреннего интерфейса sso-сервера, проектирование разделения внешнего и внешнего интерфейса sso-клиента, разработка решения для синхронизации/миграции пользовательских данных.
Предоставьте: Демонстрационные примеры, которые можно запускать напрямую, которые помогут вам быстро ознакомиться с общим процессом входа в систему единого входа.
Обеспечьте: Глубокую детальную оптимизацию, предотвращение потери параметров: автор протестировал несколько инфраструктур единого входа, и все параметры были потеряны. Например, до входа в систему это было: http://a.com?id=1&name=2, а после успешного входа стало: http://a.com?id=1. Sa-Token-SSO имеет специальный алгоритм, гарантирующий, что параметры не будут потеряны, а исходный путь будет точно возвращен после успешного входа в систему.

🍂 аутентификация авторизации OAuth2

Модуль Sa-Token OAuth2 разделен на четыре режима авторизации для удовлетворения потребностей авторизации в различных сценариях.

Модель авторизации	Введение
Формат кода авторизации	Стандартные шаги авторизации OAuth2: серверная сторона выпускает код, а клиентская сторона получает код кода и выкупает его для access_token
Скрытый	Альтернативный вариант: сервер использует перенаправление URL-адресов для прямой передачи access_token на клиентскую страницу
Тип пароля	Клиент напрямую обменивает пароль учетной записи пользователя на авторизацию access_token
Тип сертификата клиента	Серверный client_token для уровня клиента представляет авторизацию ресурса самого приложения

Подробный справочный документ: https://sa-token.com/doc.html#/oauth2/readme

📖❓ Вопросы и ответы

1. Достаточно ли функционален Sa-Token?

Семь лет напряженной работы: пять основных модулей (вход в систему, аутентификация, единый вход, OAuth2, микросервисы) + множество практических плагинов (короткий токен, интеграция jwt, подпись параметров API, авторизация ключа API...). Мы обеспечиваем не только аутентификацию разрешений, мы предоставляем универсальное решение.

2. Легко ли освоить Sa-Token?

Документация на китайском языке + комментарии к коду на китайском языке + китайское коммуникационное сообщество + большое количество блогов с практическими примерами + множество видеоуроков + большое количество выдающихся примеров интеграции проектов с открытым исходным кодом.

3. Много ли людей используют Sa-Token?

По состоянию на дату статистики (25 января 2026 г.) Sa-Token находится в:

Подписчики Gitee получили 48627 звезд, заняв первое место в списке всех рекомендуемых проектов на платформе. — Внимание GitHub достигло 18523 звезд, что в 1,97 раза больше, чем у основного конкурирующего фреймворка Spring Security, и в 4,19 раза больше, чем у Apache Shiro.
25+ фан-групп WeChat (500 человек), 8+ фан-групп QQ (1000 или 2000 человек), онлайн-посещения документов с ежемесячным PV более 200 000 человек.

Это данные, за которые многие разработчики проголосовали ногами. Я считаю, что эти данные могут доказать популярность Sa-Token лучше любых слов.

4. Какую авторитетную сертификацию имеет Sa-Token?

Награды включают, помимо прочего: Самый ценный проект с открытым исходным кодом Gitee GVP, Высококачественный проект с открытым исходным кодом GitCode G-Star, Индекс популярности TOP 30 проектов с открытым исходным кодом OSCHINA 2021, Одно из самых популярных китайских сообществ проектов с открытым исходным кодом OSCHINA 2022, Быстрорастущий проект с открытым исходным кодом Open Atomic Foundation 2023, Лучший проект организации Dromara (один), Подготовительный член Trusted Open Source Сообщество сообщества и сообщество открытого исходного кода «Dromara», где он работает. Выиграли второй приз в «Конкурсе инноваций и инвестиций в области развития Интернета в Китае 2024 года (с открытым исходным кодом)». Проект Gitee High Star (5000+звезд). Два лучших проекта Gitee с открытым исходным кодом для разработки веб-приложений в 2025 году.

5. Взимается ли плата за Sa-Token?

Sa-Token использует протокол с открытым исходным кодом Apache-2.0 и обещает, что сама платформа и онлайн-документы всегда будут бесплатными и открытыми. Конечно, если вы заинтересованы в спонсировании Sa-Token, мы не будем уклоняться от этого: Спонсорская ссылка. Мы будем регулярно синхронизировать список спонсоров с онлайн-дисплеем документов. (Одна вещь, которую вам следует отметить: это спонсорство является только дружественным спонсорством и не предполагает какого-либо коммерческого обмена)

6. Является ли Sa-Token инкапсулированным SpringSecurity? Это оболочка ApacheShiro?

нет. Sa-Token — это не бэкэнд-шаблон и не вторичная оболочка инкапсуляции для платформы xx, а чистый фреймворк собственной разработки, начинающийся с нуля, с нулевой зависимостью от основного пакета, полностью независимым и управляемым ядром архитектуры + интегрированной адаптацией многих основных фреймворков.

Сертификат ⭐ Трофей 🏆 Почетный знак

🚀 Отличные примеры интеграции с открытым исходным кодом

[ Snowy ]: первая в Китае платформа быстрой разработки, которая разделяет национальные секреты до и после, используя Vue3 + Vite + SpringBoot + MP + HuTool + SaToken.
[ RuoYi-Vue-Plus ]: переписать все функции RuoYi-Vue и интегрировать Sa-Token, Mybatis-Plus, Xxl-Job, нож4j и OSS для регулярной синхронизации.
[ Smart-Admin ]: SmartAdmin — это первая отечественная платформа быстрой разработки с «высококачественным кодом» в качестве ядра и «простым, эффективным и безопасным» промежуточным и серверным компонентами.
[ Chengdan ]: низкокодовый генератор Chengdan на Тайване. Он может полностью поддерживать несколько приложений, несколько арендаторов, несколько каналов, рабочие процессы, свободное сочетание стеков технологий платформы и т. д.
[ Deng Deng ]: платформа быстрой разработки среднего и внутреннего уровня, ориентированная на многопользовательские решения. Поддержка независимой базы данных, общей архитектуры данных и режима без арендатора ✨
[ Блог Shiyi ]: система блогов vue + Springboot, которая разделяет переднюю и заднюю части.

Есть и другие отличные кейсы с открытым исходным кодом, которые невозможно отобразить по одному. См.: Awesome-Sa-Token

🌍 Другие языковые версии

Члены сообщества Sa-Token предоставили многоязычные версии реализации:

Версия Rust: https://github.com/sa-tokens/sa-token-rust
Версия Go: https://github.com/sa-tokens/sa-token-go
Версия NodeJS: https://github.com/xiaoLangtou/xlt-token
Версия PHP: https://gitee.com/jinan-jimeng-network_0/real-token

Мы искренне приглашаем разработчиков, более владеющих вышеуказанными языками, вместе создавать соответствующие версии. 🤝

🔗 Дружественные ссылки

[ OkHttps ]: облегченная платформа HTTP-связи, чрезвычайно элегантный API, поддержка протоколов WebSocket и Stomp.
[ Forest ]: декларативная и программная двойная обработка, благодаря которой отправка HTTP-запросов становится проще.
[ Bean Searcher ]: REST-версия GraphQL — границы определения сущностей, запросы на основе параметров и одна строка кода для реализации сложных запросов!
[ Jpom ]: простое и легкое программное обеспечение для онлайн-сборки с низким уровнем вмешательства, автоматического развертывания, ежедневной эксплуатации и обслуживания, а также программного обеспечения для мониторинга проекта.
[ TLog ]: облегченный артефакт отслеживания тегов распределенного журнала.
[ hippo4j ]: мощная платформа динамического пула потоков с функциями мониторинга и оповещения.
[ hertzbeat ]: простая в использовании и дружественная система мониторинга и сигнализации в реальном времени с открытым исходным кодом, не требующая агента, высокопроизводительный кластер и мощные возможности настраиваемого мониторинга.
[ Solon ]: более современная среда разработки приложений: более быстрая, компактная и бесплатная.
[ Chat2DB ]: инструмент управления базами данных и бизнес-аналитики на основе искусственного интеллекта, который поддерживает управление 22 базами данных, такими как Mysql, pg, Oracle и Redis.

📦 Хостинг кода

Gitee：https://gitee.com/dromara/sa-token
GitHub：https://github.com/dromara/sa-token
AtomGit：https://atomgit.com/dromara/sa-token

📚 Сборник примеров

Мы отдельно подготовили соответствующие примеры интеграции почти для всех технических моментов платформы. Этот сжатый пакет содержит в общей сложности более 60 демо: охватывающих все аспекты аутентификации и аутентификации, такие как аутентификация входа в систему Sa-Token, аутентификация органа, единый вход в систему, унифицированная аутентификация OAUth2, аутентификация микросервисов, аутентификация по ключу API, интеграция JWT, проверка подписи параметров межсистемного вызова и т. д.

Адрес загрузки: https://sa-token.com/doc.html#/more/download-demos

💬 Группа связи

Группа связи QQ: 1098917026 Нажмите, чтобы присоединиться

Группа связи WeChat:

PS: Отсканируйте QR-код, чтобы добавить WeChat (примечание: sa-token), чтобы пригласить вас присоединиться к групповому чату.

Преимущества присоединения к групповому чату:

Получайте уведомления об обновлениях платформы как можно скорее.
Получайте уведомления об ошибках фреймворка как можно скорее.
Получайте уведомления о новых случаях с открытым исходным кодом как можно скорее.
Общайтесь (хуа шуу) друг с другом (мо ю) со многими большими парнями 🖐️🐟️.

40 KiB Raw Permalink Blame History Unescape Escape