Skip to content

Commit 9055367

Browse files
loong10kloong10k
committed
docs: 新增中英双语 README（README.md + README.zh-CN.md）
1 parent 0814a48 commit 9055367

2 files changed

Lines changed: 384 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# security-jwt-extension
2+
3+
![Java](https://img.shields.io/badge/Java-8-orange) ![License](https://img.shields.io/badge/License-Apache%202.0-blue)
4+
5+
JWT authentication and authorization utilities for Spring Security. This module extends the Spring Security authentication model with JWT-aware tokens and filters, for both the servlet (Web) and reactive (WebFlux) stacks.
6+
7+
## Table of Contents
8+
9+
- [1. Project Overview](#1-project-overview)
10+
- [2. Features & Status](#2-features--status)
11+
- [3. Requirements & Compatibility](#3-requirements--compatibility)
12+
- [4. Architecture & Modules](#4-architecture--modules)
13+
- [5. Installation](#5-installation)
14+
- [6. Quick Start](#6-quick-start)
15+
- [7. Configuration](#7-configuration)
16+
- [8. Core Usage / API](#8-core-usage--api)
17+
- [9. Testing & Build](#9-testing--build)
18+
- [10. Versioning & Branches](#10-versioning--branches)
19+
- [11. Contributing & License](#11-contributing--license)
20+
21+
## 1. Project Overview
22+
23+
**What it is**
24+
25+
`security-jwt-extension` provides JWT-oriented building blocks for Spring Security applications: authentication tokens carrying a JWT principal/credentials plus optional request metadata (signature, longitude, latitude), a reactive JWT authentication web filter, a servlet-side authorization success handler, and a token-refresh REST endpoint placeholder.
26+
27+
**What it is not**
28+
29+
- It is not a JWT library — token creation/parsing is delegated to your application or the underlying Spring Security infrastructure.
30+
- It is not a complete Spring Security starter: no auto-configuration is shipped in this module; wire the components into your own `SecurityFilterChain` / `SecurityWebFilterChain`.
31+
32+
**Typical scenarios**
33+
34+
| Scenario | Description |
35+
| :--- | :--- |
36+
| Servlet + JWT authorization | Attach `JwtAuthorizationSuccessHandler` to your authorization flow to build the response after a successful JWT check. |
37+
| WebFlux + JWT authentication | Use `JwtAuthenticationWebFilter` with a `ReactiveAuthenticationManager` that validates JWT credentials. |
38+
| Token refresh endpoint (WIP) | `RefreshTokenEndpoint` marks the intended location of a refresh-token REST endpoint. |
39+
40+
## 2. Features & Status
41+
42+
| Capability | Status | Notes |
43+
| :--- | :--- | :--- |
44+
| `JwtAuthenticationToken` | Available | Servlet authentication token with principal/credentials, `sign`, `longitude`, `latitude` metadata. |
45+
| `JwtAuthorizationToken` | Available | Authorization-phase token with the same metadata fields. |
46+
| `JwtAuthenticationWebFilter` | Available | WebFlux filter over `ReactiveAuthenticationManager`. |
47+
| `JwtAuthorizationSuccessHandler` | Available | Servlet `AuthenticationSuccessHandler` for authorization success responses. |
48+
| `RefreshTokenEndpoint` | WIP | `@RestController` placeholder; no endpoints implemented yet. |
49+
50+
> Status is reported as of `1.0.x.20260630-SNAPSHOT` on the `feature/1.0.x` branch.
51+
52+
## 3. Requirements & Compatibility
53+
54+
| Item | Version |
55+
| :--- | :--- |
56+
| JDK | 8+ |
57+
| Maven | 3.0+ (Maven Wrapper 3.5.0 bundled) |
58+
| Spring Security | 5.6.0 (`spring-security-core`, `spring-security-web`) |
59+
| Spring Framework | 5.3.39 (`spring-web`, `spring-webflux`) |
60+
| Jackson | 2.17.2 (`jackson-databind`) |
61+
| easy4j dependency | `io.github.easy4j:spring-security-extension` |
62+
63+
**Version lines**
64+
65+
| Branch | JDK baseline | Version pattern |
66+
| :--- | :--- | :--- |
67+
| `feature/1.0.x` | JDK 8 | `1.0.x.*` |
68+
| `feature/2.0.x` | JDK 17 | `2.0.x.*` |
69+
| `feature/3.0.x` | JDK 21 | `3.0.x.*` |
70+
71+
## 4. Architecture & Modules
72+
73+
```text
74+
Servlet / WebFlux client (Bearer JWT)
75+
|
76+
+--(servlet)--> JwtAuthorizationSuccessHandler
77+
|
78+
+--(webflux)--> JwtAuthenticationWebFilter
79+
| ReactiveAuthenticationManager
80+
v
81+
JwtAuthenticationToken / JwtAuthorizationToken
82+
| (sign, longitude, latitude)
83+
v
84+
Spring Security (core)
85+
|
86+
+-- RefreshTokenEndpoint (WIP, REST)
87+
```
88+
89+
This is a **single-module** project (packaging `jar`):
90+
91+
| Module / artifact | Role |
92+
| :--- | :--- |
93+
| `security-jwt-extension` | JWT tokens, filters and handlers for Spring Security (servlet + WebFlux). |
94+
95+
## 5. Installation
96+
97+
The artifact is not yet published to Maven Central. Resolve it from the project's configured artifact repository (Aliyun Packages) or install it locally from source; the snapshot version currently used on the `feature/1.0.x` branch is `1.0.x.20260630-SNAPSHOT`.
98+
99+
**Maven**
100+
101+
```xml
102+
<dependency>
103+
<groupId>io.github.easy4j</groupId>
104+
<artifactId>security-jwt-extension</artifactId>
105+
<version>1.0.x.20260630-SNAPSHOT</version>
106+
</dependency>
107+
```
108+
109+
**Gradle**
110+
111+
```groovy
112+
implementation 'io.github.easy4j:security-jwt-extension:1.0.x.20260630-SNAPSHOT'
113+
```
114+
115+
## 6. Quick Start
116+
117+
Build a JWT authentication token and let the reactive filter hand it to your `ReactiveAuthenticationManager`:
118+
119+
```java
120+
import org.springframework.security.boot.jwt.authentication.JwtAuthenticationToken;
121+
import org.springframework.security.boot.jwt.authentication.JwtAuthenticationWebFilter;
122+
import org.springframework.security.authentication.ReactiveAuthenticationManager;
123+
124+
// 1. Token
125+
JwtAuthenticationToken token =
126+
new JwtAuthenticationToken(principal, jwtCredentials);
127+
token.setSign("optional-request-sign");
128+
token.setLongitude(116.397128d);
129+
token.setLatitude(39.916527d);
130+
131+
// 2. Reactive filter wired with your JWT-validating manager
132+
ReactiveAuthenticationManager manager = /* your manager */;
133+
JwtAuthenticationWebFilter filter = new JwtAuthenticationWebFilter(manager);
134+
```
135+
136+
**Expected result:** incoming requests matched by the filter are authenticated against the manager using the JWT credentials carried by `JwtAuthenticationToken`.
137+
138+
## 7. Configuration
139+
140+
This is a pure library: no configuration properties, no property prefix, no auto-configuration. All components are instantiated and wired by the application.
141+
142+
## 8. Core Usage / API
143+
144+
| Class | Package | Role |
145+
| :--- | :--- | :--- |
146+
| `JwtAuthenticationToken` | `org.springframework.security.boot.jwt.authentication` | `AbstractAuthenticationToken` subclass for the authentication phase. |
147+
| `JwtAuthorizationToken` | `org.springframework.security.boot.jwt.authorization` | Token for the authorization phase (same metadata fields). |
148+
| `JwtAuthenticationWebFilter` | `org.springframework.security.boot.jwt.authentication` | WebFlux `AuthenticationWebFilter` using a `ReactiveAuthenticationManager`. |
149+
| `JwtAuthorizationSuccessHandler` | `org.springframework.security.boot.jwt.authorization` | Servlet `AuthenticationSuccessHandler`; also exposes `clearAuthenticationAttributes`. |
150+
| `RefreshTokenEndpoint` | `org.springframework.security.boot.jwt.endpoint` | `@RestController` placeholder (no endpoints yet). |
151+
152+
Servlet-style authorization success handling:
153+
154+
```java
155+
import org.springframework.security.boot.jwt.authorization.JwtAuthorizationSuccessHandler;
156+
157+
JwtAuthorizationSuccessHandler handler = new JwtAuthorizationSuccessHandler();
158+
// Called by your authorization flow when the JWT check succeeds
159+
handler.onAuthenticationSuccess(request, response, authentication);
160+
```
161+
162+
## 9. Testing & Build
163+
164+
```bash
165+
# Full build with JaCoCo coverage report/check
166+
./mvnw clean verify
167+
168+
# Install into the local repository
169+
./mvnw install
170+
```
171+
172+
Test & gate facts (as configured in the pom):
173+
174+
- No unit tests exist in this module yet.
175+
- JaCoCo is bound to `prepare-agent` / `report` / `check`; the `check` rule requires a **90% line coverage ratio** (configured with `haltOnFailure=false`).
176+
177+
## 10. Versioning & Branches
178+
179+
| Branch | JDK baseline | Version pattern | Status |
180+
| :--- | :--- | :--- | :--- |
181+
| `feature/1.0.x` | JDK 8 | `1.0.x.*` | Active; current snapshot `1.0.x.20260630-SNAPSHOT` |
182+
| `feature/2.0.x` | JDK 17 | `2.0.x.*` | Maintained |
183+
| `feature/3.0.x` | JDK 21 | `3.0.x.*` | Maintained |
184+
185+
Maintenance strategy: the 1.0.x line keeps JDK 8 compatibility for legacy deployments; the 2.0.x and 3.0.x lines are the modern JDK baselines. Release artifacts are published to the project's configured artifact repository (Aliyun Packages) and GitHub Releases; the project has not yet published to Maven Central.
186+
187+
## 11. Contributing & License
188+
189+
Contributions are welcome — please open an issue or a pull request on the [GitHub repository](https://github.com/easy-4-java/security-jwt-extension).
190+
191+
This project is licensed under the **Apache License 2.0**. See [LICENSE](LICENSE) for details.

‎README.zh-CN.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# security-jwt-extension
2+
3+
[English](./README.md) | [简体中文](./README.zh-CN.md)
4+
5+
![Java](https://img.shields.io/badge/Java-8-orange) ![License](https://img.shields.io/badge/License-Apache%202.0-blue)
6+
7+
面向 Spring Security 的 JWT 认证与授权工具。本模块为 Spring Security 认证模型补充 JWT 感知的 Token 与过滤器，同时覆盖 Servlet（Web）与响应式（WebFlux）技术栈。
8+
9+
## 目录
10+
11+
- [1. Project Overview](#1-project-overview)
12+
- [2. Features & Status](#2-features--status)
13+
- [3. Requirements & Compatibility](#3-requirements--compatibility)
14+
- [4. Architecture & Modules](#4-architecture--modules)
15+
- [5. Installation](#5-installation)
16+
- [6. Quick Start](#6-quick-start)
17+
- [7. Configuration](#7-configuration)
18+
- [8. Core Usage / API](#8-core-usage--api)
19+
- [9. Testing & Build](#9-testing--build)
20+
- [10. Versioning & Branches](#10-versioning--branches)
21+
- [11. Contributing & License](#11-contributing--license)
22+
23+
## 1. Project Overview
24+
25+
**是什么**
26+
27+
`security-jwt-extension` 为 Spring Security 应用提供面向 JWT 的构建块：携带 JWT 主体/凭证以及可选请求元数据（签名、经度、纬度）的认证 Token、响应式 JWT 认证 Web 过滤器、Servlet 侧授权成功处理器，以及一个 Token 刷新 REST 端点占位。
28+
29+
**不是什么**
30+
31+
- 它不是 JWT 库——Token 的签发与解析由你的应用或底层 Spring Security 基础设施负责。
32+
- 它不是完整的 Spring Security Starter：本模块不提供自动配置；组件需要你在自己的 `SecurityFilterChain` / `SecurityWebFilterChain` 中装配。
33+
34+
**典型场景**
35+
36+
| 场景 | 说明 |
37+
| :--- | :--- |
38+
| Servlet + JWT 授权 | 在授权流程中接入 `JwtAuthorizationSuccessHandler`，在 JWT 校验成功后构造响应。 |
39+
| WebFlux + JWT 认证 | 使用 `JwtAuthenticationWebFilter` 配合校验 JWT 凭证的 `ReactiveAuthenticationManager`。 |
40+
| Token 刷新端点（开发中） | `RefreshTokenEndpoint` 标识 refresh-token REST 端点的预期位置。 |
41+
42+
## 2. Features & Status
43+
44+
| 能力 | 状态 | 说明 |
45+
| :--- | :--- | :--- |
46+
| `JwtAuthenticationToken` | 可用 | Servlet 认证 Token，含主体/凭证与 `sign`、`longitude`、`latitude` 元数据。 |
47+
| `JwtAuthorizationToken` | 可用 | 授权阶段 Token，元数据字段相同。 |
48+
| `JwtAuthenticationWebFilter` | 可用 | 基于 `ReactiveAuthenticationManager` 的 WebFlux 过滤器。 |
49+
| `JwtAuthorizationSuccessHandler` | 可用 | Servlet `AuthenticationSuccessHandler`，用于授权成功响应。 |
50+
| `RefreshTokenEndpoint` | 开发中 | `@RestController` 占位，尚未实现任何端点。 |
51+
52+
> 状态以 `feature/1.0.x` 分支上的 `1.0.x.20260630-SNAPSHOT` 为准。
53+
54+
## 3. Requirements & Compatibility
55+
56+
| 项目 | 版本 |
57+
| :--- | :--- |
58+
| JDK | 8+ |
59+
| Maven | 3.0+（内置 Maven Wrapper 3.5.0） |
60+
| Spring Security | 5.6.0（`spring-security-core`、`spring-security-web`） |
61+
| Spring Framework | 5.3.39（`spring-web`、`spring-webflux`） |
62+
| Jackson | 2.17.2（`jackson-databind`） |
63+
| easy4j 依赖 | `io.github.easy4j:spring-security-extension` |
64+
65+
**版本线**
66+
67+
| 分支 | JDK 基线 | 版本模式 |
68+
| :--- | :--- | :--- |
69+
| `feature/1.0.x` | JDK 8 | `1.0.x.*` |
70+
| `feature/2.0.x` | JDK 17 | `2.0.x.*` |
71+
| `feature/3.0.x` | JDK 21 | `3.0.x.*` |
72+
73+
## 4. Architecture & Modules
74+
75+
```text
76+
Servlet / WebFlux 客户端（Bearer JWT）
77+
|
78+
+--(servlet)--> JwtAuthorizationSuccessHandler
79+
|
80+
+--(webflux)--> JwtAuthenticationWebFilter
81+
| ReactiveAuthenticationManager
82+
v
83+
JwtAuthenticationToken / JwtAuthorizationToken
84+
| (sign, longitude, latitude)
85+
v
86+
Spring Security（core）
87+
|
88+
+-- RefreshTokenEndpoint（开发中，REST）
89+
```
90+
91+
本项目为**单模块**工程（packaging 为 `jar`）：
92+
93+
| 模块 / 构件 | 职责 |
94+
| :--- | :--- |
95+
| `security-jwt-extension` | 面向 Spring Security 的 JWT Token、过滤器与处理器（Servlet + WebFlux）。 |
96+
97+
## 5. Installation
98+
99+
该构件尚未发布到 Maven Central。请从项目配置的制品仓库（阿里云制品仓库）获取，或从源码本地安装；`feature/1.0.x` 分支当前使用的快照版本为 `1.0.x.20260630-SNAPSHOT`。
100+
101+
**Maven**
102+
103+
```xml
104+
<dependency>
105+
<groupId>io.github.easy4j</groupId>
106+
<artifactId>security-jwt-extension</artifactId>
107+
<version>1.0.x.20260630-SNAPSHOT</version>
108+
</dependency>
109+
```
110+
111+
**Gradle**
112+
113+
```groovy
114+
implementation 'io.github.easy4j:security-jwt-extension:1.0.x.20260630-SNAPSHOT'
115+
```
116+
117+
## 6. Quick Start
118+
119+
构造 JWT 认证 Token，并交给响应式过滤器转发给你的 `ReactiveAuthenticationManager`：
120+
121+
```java
122+
import org.springframework.security.boot.jwt.authentication.JwtAuthenticationToken;
123+
import org.springframework.security.boot.jwt.authentication.JwtAuthenticationWebFilter;
124+
import org.springframework.security.authentication.ReactiveAuthenticationManager;
125+
126+
// 1. Token
127+
JwtAuthenticationToken token =
128+
new JwtAuthenticationToken(principal, jwtCredentials);
129+
token.setSign("optional-request-sign");
130+
token.setLongitude(116.397128d);
131+
token.setLatitude(39.916527d);
132+
133+
// 2. 用你的 JWT 校验管理器装配响应式过滤器
134+
ReactiveAuthenticationManager manager = /* 你的管理器 */;
135+
JwtAuthenticationWebFilter filter = new JwtAuthenticationWebFilter(manager);
136+
```
137+
138+
**预期结果：** 过滤器匹配到的请求将使用 `JwtAuthenticationToken` 携带的 JWT 凭证交由管理器完成认证。
139+
140+
## 7. Configuration
141+
142+
这是纯库：没有配置属性、没有属性前缀、没有自动配置。所有组件由应用自行实例化并装配。
143+
144+
## 8. Core Usage / API
145+
146+
| 类 | 包 | 职责 |
147+
| :--- | :--- | :--- |
148+
| `JwtAuthenticationToken` | `org.springframework.security.boot.jwt.authentication` | 认证阶段的 `AbstractAuthenticationToken` 子类。 |
149+
| `JwtAuthorizationToken` | `org.springframework.security.boot.jwt.authorization` | 授权阶段的 Token（元数据字段相同）。 |
150+
| `JwtAuthenticationWebFilter` | `org.springframework.security.boot.jwt.authentication` | 基于 `ReactiveAuthenticationManager` 的 WebFlux `AuthenticationWebFilter`。 |
151+
| `JwtAuthorizationSuccessHandler` | `org.springframework.security.boot.jwt.authorization` | Servlet `AuthenticationSuccessHandler`；另暴露 `clearAuthenticationAttributes`。 |
152+
| `RefreshTokenEndpoint` | `org.springframework.security.boot.jwt.endpoint` | `@RestController` 占位（尚无端点）。 |
153+
154+
Servlet 风格授权成功处理：
155+
156+
```java
157+
import org.springframework.security.boot.jwt.authorization.JwtAuthorizationSuccessHandler;
158+
159+
JwtAuthorizationSuccessHandler handler = new JwtAuthorizationSuccessHandler();
160+
// 由你的授权流程在 JWT 校验成功后调用
161+
handler.onAuthenticationSuccess(request, response, authentication);
162+
```
163+
164+
## 9. Testing & Build
165+
166+
```bash
167+
# 完整构建（含 JaCoCo 覆盖率报告/检查）
168+
./mvnw clean verify
169+
170+
# 安装到本地仓库
171+
./mvnw install
172+
```
173+
174+
测试与门禁事实（以 pom 配置为准）：
175+
176+
- 本模块暂无单元测试。
177+
- JaCoCo 绑定 `prepare-agent` / `report` / `check`；`check` 规则要求**行覆盖率不低于 90%**（配置了 `haltOnFailure=false`）。
178+
179+
## 10. Versioning & Branches
180+
181+
| 分支 | JDK 基线 | 版本模式 | 状态 |
182+
| :--- | :--- | :--- | :--- |
183+
| `feature/1.0.x` | JDK 8 | `1.0.x.*` | 活跃；当前快照 `1.0.x.20260630-SNAPSHOT` |
184+
| `feature/2.0.x` | JDK 17 | `2.0.x.*` | 维护中 |
185+
| `feature/3.0.x` | JDK 21 | `3.0.x.*` | 维护中 |
186+
187+
维护策略：1.0.x 版本线保持 JDK 8 兼容，服务于存量部署；2.0.x 与 3.0.x 版本线为现代 JDK 基线。发布制品发布到项目配置的制品仓库（阿里云制品仓库）与 GitHub Releases；项目尚未发布到 Maven Central。
188+
189+
## 11. Contributing & License
190+
191+
欢迎参与贡献——请在 [GitHub 仓库](https://github.com/easy-4-java/security-jwt-extension) 提交 Issue 或 Pull Request。
192+
193+
本项目基于 **Apache License 2.0** 开源。详见 [LICENSE](LICENSE)。

0 commit comments

Comments
 (0)