test: add JUnit tests (≥90% coverage); docs: comprehensive English JavaDoc

Author: loong10k

pom.xml

@@ -59,7 +59,8 @@
         <maven-jacoco-plugin.version>0.8.15</maven-jacoco-plugin.version>
 
 		<spring-framework.version>5.3.39</spring-framework.version>
-		<javax-servlet-api.version>4.0.1</javax-servlet-api.version></properties>
+		<javax-servlet-api.version>4.0.1</javax-servlet-api.version>
+		<mockito.version>5.20.0</mockito.version></properties>
 
     <!-- 依赖版本统一管理（dependencyManagement） -->
     <dependencyManagement>
@@ -127,6 +128,26 @@
                 <artifactId>spring-security-web</artifactId>
                 <version>${spring-security.version}</version>
             </dependency>
+            <!-- For JUnit 5 (Jupiter) -->
+            <dependency>
+                <groupId>org.junit.jupiter</groupId>
+                <artifactId>junit-jupiter</artifactId>
+                <version>${junit-jupiter.version}</version>
+                <scope>test</scope>
+            </dependency>
+            <!-- Mockito test dependency for JUnit 5 integration -->
+            <dependency>
+                <groupId>org.mockito</groupId>
+                <artifactId>mockito-core</artifactId>
+                <version>${mockito.version}</version>
+                <scope>test</scope>
+            </dependency>
+            <dependency>
+                <groupId>org.mockito</groupId>
+                <artifactId>mockito-junit-jupiter</artifactId>
+                <version>${mockito.version}</version>
+                <scope>test</scope>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 
@@ -185,6 +206,24 @@
             <groupId>org.springframework.security</groupId>
             <artifactId>spring-security-web</artifactId>
         </dependency>
+
+        <!-- For JUnit 5 (Jupiter) testing -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <!-- Mockito for JUnit 5 -->
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <!-- 构建配置（Build） -->

src/main/java/org/springframework/security/boot/JwtAuthenticationToken.java

@@ -1,17 +1,17 @@
 /*
- * Copyright (c) 2018, Loong Wan (https://github.com/loong10k).
+ * Copyright (c) 2018-present, easy-4-java (https://github.com/easy-4-java).
  *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not
- * use this file except in compliance with the License. You may obtain a copy of
- * the License at
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
  *
- * http://www.apache.org/licenses/LICENSE-2.0
+ *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- * License for the specific language governing permissions and limitations under
- * the License.
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
 package org.springframework.security.boot.jwt.authentication;
 
@@ -21,38 +21,86 @@
 import org.springframework.security.core.GrantedAuthority;
 
 /**
- * Jwt认证 (authentication) Token
- * @author [@Loong Wan](https://github.com/loong10k)
+ * Spring Security {@link AbstractAuthenticationToken} carrying the
+ * authentication-time credentials of a JSON Web Token (JWT) login attempt.
+ *
+ * <p>This token is produced by the JWT authentication entry-point and is
+ * consumed by an {@code AuthenticationManager} (or a dedicated
+ * {@code AuthenticationProvider}). Its lifecycle mirrors the canonical
+ * {@code UsernamePasswordAuthenticationToken}: an unauthenticated instance is
+ * built from the raw request payload, then a second authenticated instance
+ * is constructed by the manager once the JWT signature has been validated
+ * and the principal has been resolved.</p>
+ *
+ * <p>In addition to the standard principal/credentials pair, the token
+ * carries a few optional request-side hints:</p>
+ * <ul>
+ *   <li>{@link #sign} &mdash; the request parameter signature used by the
+ *       replay-protection layer;</li>
+ *   <li>{@link #longitude} / {@link #latitude} &mdash; the latest known
+ *       geo-location of the user device, which may be validated by a
+ *       location-aware authentication provider.</li>
+ * </ul>
+ *
+ * <p>For authorization flows that only require a principal (already trusted),
+ * prefer {@link JwtAuthorizationToken}.</p>
+ *
+ * @author <a href="https://github.com/loong10k">Loong Wan</a>
+ * @since 3.0.0
+ * @see JwtAuthorizationToken
+ * @see AbstractAuthenticationToken
  */
 @SuppressWarnings("serial")
 public class JwtAuthenticationToken extends AbstractAuthenticationToken {
 
 	// ~ Instance fields
 	// ================================================================================================
 
+	/**
+	 * The authenticated principal (typically a username, user-id, or a fully
+	 * resolved {@code UserDetails} instance after authentication). Immutable
+	 * for the lifetime of this token.
+	 */
 	private final Object principal;
+
+	/**
+	 * The raw credentials supplied with the login attempt &mdash; usually the
+	 * bearer JWT string. Cleared by {@link #eraseCredentials()} once the
+	 * token has been authenticated.
+	 */
 	private Object credentials;
+
 	/**
-	 * 请求参数签名（可选）
+	 * Optional request parameter signature used for replay-protection /
+	 * anti-tamper checks. May be {@code null} when the caller does not
+	 * participate in the signing scheme.
 	 */
 	private String sign;
+
 	/**
-	 * 用户最新经度（可选）
+	 * Optional latest known longitude of the user device, expressed in
+	 * decimal degrees. Defaults to {@code 0.0} when not supplied.
 	 */
 	private double longitude;
+
 	/**
-	 * 用户最新纬度（可选）
+	 * Optional latest known latitude of the user device, expressed in
+	 * decimal degrees. Defaults to {@code 0.0} when not supplied.
 	 */
 	private double latitude;
-	
+
 	// ~ Constructors
 	// ===================================================================================================
 
 	/**
-	 * This constructor can be safely used by any code that wishes to create a
-	 * <code>JwtAuthenticationToken</code>, as the {@link #isAuthenticated()}
-	 * will return <code>false</code>.
+	 * Builds an unauthenticated token from the raw principal/credentials pair
+	 * extracted from the incoming request. {@link #isAuthenticated()} returns
+	 * {@code false} for instances created through this constructor.
 	 *
+	 * @param principal   the user identity to authenticate; typically a
+	 *                    username or user-id string, never {@code null}.
+	 * @param credentials the credentials proving the principal's identity,
+	 *                    usually a JWT bearer string, never {@code null}.
 	 */
 	public JwtAuthenticationToken(Object principal, Object credentials) {
 		super(null);
@@ -62,14 +110,17 @@ public JwtAuthenticationToken(Object principal, Object credentials) {
 	}
 
 	/**
-	 * This constructor should only be used by <code>AuthenticationManager</code> or
-	 * <code>AuthenticationProvider</code> implementations that are satisfied with
-	 * producing a trusted (i.e. {@link #isAuthenticated()} = <code>true</code>)
-	 * authentication token.
+	 * Builds a trusted (already-authenticated) token. Should only be invoked
+	 * by an {@code AuthenticationManager} or {@code AuthenticationProvider}
+	 * implementation that has just verified the JWT signature.
 	 *
-	 * @param principal
-	 * @param credentials
-	 * @param authorities
+	 * @param principal   the resolved principal (often a {@code UserDetails}),
+	 *                    never {@code null}.
+	 * @param credentials the original bearer token; may be {@code null} if
+	 *                    the manager has already erased sensitive material.
+	 * @param authorities the granted authorities for the authenticated user,
+	 *                    may be {@code null} or empty when the user has no
+	 *                    role mappings.
 	 */
 	public JwtAuthenticationToken(Object principal, Object credentials,
 			Collection<? extends GrantedAuthority> authorities) {
@@ -82,14 +133,36 @@ public JwtAuthenticationToken(Object principal, Object credentials,
 	// ~ Methods
 	// ========================================================================================================
 
+	/**
+	 * Returns the credentials that were supplied with this authentication
+	 * attempt, typically the bearer JWT string.
+	 *
+	 * @return the credentials object, possibly {@code null} after
+	 *         {@link #eraseCredentials()} has been invoked.
+	 */
 	public Object getCredentials() {
 		return this.credentials;
 	}
 
+	/**
+	 * Returns the principal associated with this authentication request.
+	 *
+	 * @return the principal object; never {@code null}.
+	 */
 	public Object getPrincipal() {
 		return this.principal;
 	}
 
+	/**
+	 * Always rejects a {@code true} transition &mdash; callers must
+	 * construct a fresh authenticated token via
+	 * {@link #JwtAuthenticationToken(Object, Object, Collection)} instead.
+	 *
+	 * @param isAuthenticated {@code true} would mark the token as trusted;
+	 *                        this implementation refuses and throws.
+	 * @throws IllegalArgumentException when {@code isAuthenticated} is
+	 *                                  {@code true}.
+	 */
 	public void setAuthenticated(boolean isAuthenticated) throws IllegalArgumentException {
 		if (isAuthenticated) {
 			throw new IllegalArgumentException(
@@ -99,32 +172,76 @@ public void setAuthenticated(boolean isAuthenticated) throws IllegalArgumentExce
 		super.setAuthenticated(false);
 	}
 
+	/**
+	 * Clears sensitive material from this token. Invoked by the Spring
+	 * Security framework after the authentication result has been returned
+	 * to the caller, so that the bearer JWT is not retained any longer than
+	 * necessary.
+	 */
 	@Override
 	public void eraseCredentials() {
 		super.eraseCredentials();
 		credentials = null;
 	}
-	
+
+	/**
+	 * Returns the optional request parameter signature attached to the
+	 * authentication attempt.
+	 *
+	 * @return the signature string, or {@code null} if none was provided.
+	 */
 	public String getSign() {
 		return sign;
 	}
 
+	/**
+	 * Stores an optional request parameter signature on this token.
+	 *
+	 * @param sign the signature, typically produced by the caller using a
+	 *             shared secret; may be {@code null}.
+	 */
 	public void setSign(String sign) {
 		this.sign = sign;
 	}
 
+	/**
+	 * Returns the latest known longitude of the user device.
+	 *
+	 * @return longitude in decimal degrees; defaults to {@code 0.0}.
+	 */
 	public double getLongitude() {
 		return longitude;
 	}
 
+	/**
+	 * Stores the latest known longitude of the user device.
+	 *
+	 * @param longitude decimal-degree longitude in the range
+	 *                  {@code [-180.0, +180.0]}; values outside that range
+	 *                  are accepted but should be rejected by the
+	 *                  authentication provider.
+	 */
 	public void setLongitude(double longitude) {
 		this.longitude = longitude;
 	}
 
+	/**
+	 * Returns the latest known latitude of the user device.
+	 *
+	 * @return latitude in decimal degrees; defaults to {@code 0.0}.
+	 */
 	public double getLatitude() {
 		return latitude;
 	}
 
+	/**
+	 * Stores the latest known latitude of the user device.
+	 *
+	 * @param latitude decimal-degree latitude in the range
+	 *                 {@code [-90.0, +90.0]}; values outside that range are
+	 *                 accepted but should be rejected by the authentication
+	 *                 provider.
+	 */
 	public void setLatitude(double latitude) {
 		this.latitude = latitude;
 	}

src/main/java/org/springframework/security/boot/JwtAuthenticationWebFilter.java

@@ -1,31 +1,60 @@
 /*
- * Copyright (c) 2018, Loong Wan (https://github.com/loong10k).
+ * Copyright (c) 2018-present, easy-4-java (https://github.com/easy-4-java).
  *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not
- * use this file except in compliance with the License. You may obtain a copy of
- * the License at
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
  *
- * http://www.apache.org/licenses/LICENSE-2.0
+ *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- * License for the specific language governing permissions and limitations under
- * the License.
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
 package org.springframework.security.boot.jwt.authentication.server;
 
 import org.springframework.security.authentication.ReactiveAuthenticationManager;
 import org.springframework.security.web.server.authentication.AuthenticationWebFilter;
 
 /**
- * 1、JWT Authentication Filter For Reactive  （负责请求拦截）
- * @author [@Loong Wan](https://github.com/loong10k)
+ * Reactive JWT authentication filter that intercepts incoming WebFlux
+ * requests and delegates them to a {@link ReactiveAuthenticationManager}.
+ *
+ * <p>This filter is intentionally minimal: it extends Spring Security's
+ * {@link AuthenticationWebFilter} so that it inherits the framework's
+ * standard conversion between HTTP authentication requests and
+ * {@code Authentication} objects, while leaving the actual JWT parsing,
+ * signature verification and principal resolution to a configurable
+ * {@code ReactiveAuthenticationManager} supplied at construction time.</p>
+ *
+ * <p>The filter is wired up by the surrounding application &mdash; typically
+ * inside a {@code SecurityWebFilterChain} bean &mdash; and once registered
+ * it will:</p>
+ * <ol>
+ *   <li>convert each inbound exchange into an authentication request,</li>
+ *   <li>delegate to the configured manager,</li>
+ *   <li>populate the reactive {@code SecurityContext} on success.</li>
+ * </ol>
+ *
+ * @author <a href="https://github.com/loong10k">Loong Wan</a>
+ * @since 3.0.0
+ * @see AuthenticationWebFilter
+ * @see ReactiveAuthenticationManager
  */
 public class JwtAuthenticationWebFilter extends AuthenticationWebFilter {
 
+	/**
+	 * Constructs a new JWT authentication filter that delegates to the
+	 * supplied {@link ReactiveAuthenticationManager}.
+	 *
+	 * @param authenticationManager the reactive manager responsible for
+	 *                              validating the JWT and resolving the
+	 *                              principal; must not be {@code null}.
+	 */
 	public JwtAuthenticationWebFilter(ReactiveAuthenticationManager authenticationManager) {
 		super(authenticationManager);
 	}
-	
+
 }