From a8c349bd751ff959d2029d501a3c932f6e037c0a Mon Sep 17 00:00:00 2001 From: zihluwang Date: Fri, 9 Jan 2026 09:17:01 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20Javadoc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- config/application-prod.yml.example | 8 +-- .../onixbyte/helix/config/WebFluxConfig.java | 57 ------------------- .../helix/controller/AssetController.java | 5 +- .../helix/controller/AuthController.java | 16 ++++++ .../helix/controller/AuthorityController.java | 29 +++++++++- .../helix/controller/CaptchaController.java | 11 ++++ .../controller/DepartmentController.java | 6 ++ .../helix/controller/ExceptionController.java | 16 +----- .../helix/controller/MenuController.java | 11 ++++ .../helix/controller/PositionController.java | 13 +++++ .../helix/controller/RoleController.java | 6 ++ .../helix/controller/SettingController.java | 9 ++- .../helix/controller/UserController.java | 41 +++++++++++-- .../domain/web/response/ActionResponse.java | 15 +++++ 14 files changed, 154 insertions(+), 89 deletions(-) delete mode 100644 src/main/java/com/onixbyte/helix/config/WebFluxConfig.java create mode 100644 src/main/java/com/onixbyte/helix/domain/web/response/ActionResponse.java diff --git a/config/application-prod.yml.example b/config/application-prod.yml.example index 101e908..f5b3e37 100644 --- a/config/application-prod.yml.example +++ b/config/application-prod.yml.example @@ -26,9 +26,9 @@ app: # 是否开启 S3 文件存储服务 enabled: true # S3 服务端点（若使用非 AWS 提供的 S3 兼容 API，请添加该配置） -# endpoint: https://endpoint.s3.service + # endpoint: https://endpoint.s3.service # S3 服务区域（详情请见 S3 服务提供商） -# region: apac + # region: apac # 公开域名 public-host: https://s3.my.app # 是否开启 Path Style @@ -64,8 +64,8 @@ app: # 允许的请求头列表 allowed-headers: Content-Type # 允许的请求方法列表（Ref org.springframework.http.HttpMethod） - # 2025.11.6注 - # 由于 Spring 解析问题，在此处使用小写的情况下会导致在请求头中存在 Origin 时出现 Invalid CORS Request 的问题，请务必使用大写 + # Spring HttpMethod 并非 enum class，因此在此处使用小写请求方式会导致在请求头中存在 Origin 时出现 Invalid + # CORS Request 的问题，请务必使用大写 allowed-methods: - GET - POST diff --git a/src/main/java/com/onixbyte/helix/config/WebFluxConfig.java b/src/main/java/com/onixbyte/helix/config/WebFluxConfig.java deleted file mode 100644 index 6dae4eb..0000000 --- a/src/main/java/com/onixbyte/helix/config/WebFluxConfig.java +++ /dev/null @@ -1,57 +0,0 @@ -package com.onixbyte.helix.config; - -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; -import org.springframework.web.reactive.function.client.WebClient; - -/** - * Configuration class for Spring WebFlux reactive web components. - *

- * This configuration class provides beans for reactive web programming components within the Helix - * application. It configures WebClient instances and other reactive web-related components that - * enable non-blocking, asynchronous HTTP communication with external services. - *

- * The configuration supports: - *

- * - * @author zihluwang - * @since 1.0.0 - * @see WebClient - * @see Configuration - */ -@Configuration -public class WebFluxConfig { - - /** - * Creates a reactive WebClient for HTTP communication with external services. - *

- * This method configures a {@link WebClient} instance that provides a modern, reactive approach - * to HTTP client operations. The WebClient supports non-blocking I/O and is built on top of - * Reactor Netty, making it suitable for high-performance, scalable applications. - *

- * The client is configured with default settings and can be used throughout the application for - * making HTTP requests to external APIs, microservices, or other web resources in a reactive, - * non-blocking manner. - *

- * Key features: - *

- * - * @return a configured {@link WebClient} instance for reactive HTTP operations - * @see WebClient - * @see WebClient.Builder - */ - @Bean - public WebClient webClient() { - return WebClient.builder() - .build(); - } -} diff --git a/src/main/java/com/onixbyte/helix/controller/AssetController.java b/src/main/java/com/onixbyte/helix/controller/AssetController.java index 3ef06d7..c413f38 100644 --- a/src/main/java/com/onixbyte/helix/controller/AssetController.java +++ b/src/main/java/com/onixbyte/helix/controller/AssetController.java @@ -13,11 +13,10 @@ import org.springframework.web.bind.annotation.*; import org.springframework.web.multipart.MultipartFile; /** - * REST controller for file storage operations. Provides endpoints for uploading, downloading, and - * deleting assets using the configured storage service. + * This controller provides entry points that manipulates assets. * * @author zihluwang - * @since 1.0.0 + * @author siujamo */ @RestController @RequestMapping("/assets") diff --git a/src/main/java/com/onixbyte/helix/controller/AuthController.java b/src/main/java/com/onixbyte/helix/controller/AuthController.java index 98b4d90..1bef319 100644 --- a/src/main/java/com/onixbyte/helix/controller/AuthController.java +++ b/src/main/java/com/onixbyte/helix/controller/AuthController.java @@ -17,6 +17,12 @@ import org.springframework.web.bind.annotation.*; import java.time.Duration; +/** + * This controller provides entry points making user authorised. + * + * @author zihluwang + * @author siujamo + */ @RestController @RequestMapping("/auth") public class AuthController { @@ -57,11 +63,21 @@ public class AuthController { .body(userService.getDetail(user)); } + /** + * Get whether the registration function is enabled. + * + * @return {@code true} if registration function is enabled, otherwise {@code false} + */ @GetMapping("/register-enabled") public boolean getRegisterEnabled() { return authService.getRegisterEnabled(); } + /** + * Perform log out. + * + * @return a response that remove the authentication from cookie + */ @GetMapping("/logout") public ResponseEntity logout() { var cookie = authService.buildCookie(TokenConstant.TOKEN_NAME, "", Duration.ZERO); diff --git a/src/main/java/com/onixbyte/helix/controller/AuthorityController.java b/src/main/java/com/onixbyte/helix/controller/AuthorityController.java index 31e2a5a..5363712 100644 --- a/src/main/java/com/onixbyte/helix/controller/AuthorityController.java +++ b/src/main/java/com/onixbyte/helix/controller/AuthorityController.java @@ -7,12 +7,15 @@ import com.onixbyte.helix.domain.web.request.QueryAuthorityRequest; import com.onixbyte.helix.service.AuthorityService; import org.springframework.data.domain.Page; import org.springframework.data.domain.PageRequest; -import org.springframework.http.ResponseEntity; import org.springframework.validation.annotation.Validated; import org.springframework.web.bind.annotation.*; -import java.util.List; - +/** + * This controller provides entry points for manipulate authorities. + * + * @author zihluwang + * @author siujamo + */ @RestController @RequestMapping("/authorities") public class AuthorityController { @@ -23,6 +26,14 @@ public class AuthorityController { this.authorityService = authorityService; } + /** + * Get authorities by page. + * + * @param pageNum current page num + * @param pageSize page size + * @param request query parameters + * @return a page contains authority data of the specified page + */ @GetMapping public Page getAuthorities( @RequestParam(required = false, defaultValue = "1") Integer pageNum, @@ -33,11 +44,23 @@ public class AuthorityController { return authorityService.getAuthorities(pageRequest, request); } + /** + * Add an authority. + * + * @param request authority specs + * @return created authority + */ @PostMapping public Authority addAuthority(@Validated @RequestBody AddAuthorityRequest request) { return authorityService.addAuthority(request); } + /** + * Edit an authority. + * + * @param request authority specs + * @return edited authority + */ @PutMapping public Authority editAuthority(@Validated @RequestBody EditAuthorityRequest request) { return authorityService.editAuthority(request); diff --git a/src/main/java/com/onixbyte/helix/controller/CaptchaController.java b/src/main/java/com/onixbyte/helix/controller/CaptchaController.java index a06808c..0e63f23 100644 --- a/src/main/java/com/onixbyte/helix/controller/CaptchaController.java +++ b/src/main/java/com/onixbyte/helix/controller/CaptchaController.java @@ -10,6 +10,12 @@ import org.springframework.web.bind.annotation.RestController; import java.util.Optional; +/** + * This controller provides entry points to get captcha images. + * + * @author zihluwang + * @author siujamo + */ @RestController @RequestMapping("/captcha") public class CaptchaController { @@ -21,6 +27,11 @@ public class CaptchaController { this.captchaService = captchaService; } + /** + * Get captcha image and captcha uuid. + * + * @return captcha response, contains the uuid of the captcha and image BASE64 + */ @GetMapping public ResponseEntity getCaptcha() { var captchaTuple = captchaService.buildCaptcha(); diff --git a/src/main/java/com/onixbyte/helix/controller/DepartmentController.java b/src/main/java/com/onixbyte/helix/controller/DepartmentController.java index f8716eb..34c5a5e 100644 --- a/src/main/java/com/onixbyte/helix/controller/DepartmentController.java +++ b/src/main/java/com/onixbyte/helix/controller/DepartmentController.java @@ -10,6 +10,12 @@ import org.springframework.web.bind.annotation.RestController; import java.util.List; +/** + * This controller provides entry points that manipulates departments. + * + * @author zihluwang + * @author siujamo + */ @RestController @RequestMapping("/departments") public class DepartmentController { diff --git a/src/main/java/com/onixbyte/helix/controller/ExceptionController.java b/src/main/java/com/onixbyte/helix/controller/ExceptionController.java index 9a9b789..f8a6677 100644 --- a/src/main/java/com/onixbyte/helix/controller/ExceptionController.java +++ b/src/main/java/com/onixbyte/helix/controller/ExceptionController.java @@ -13,22 +13,10 @@ import java.time.LocalDateTime; import java.util.stream.Collectors; /** - * Global exception handler for the Helix application. - *

- * This controller advice provides centralised exception handling across all controllers in - * the application. It intercepts exceptions thrown during request processing and converts them into - * appropriate HTTP responses with standardised error formats. - *

- * The controller handles various types of exceptions including: - *

    - *
  • Business logic exceptions ({@link BizException})
    • - *
  • Bean validation constraint violations ({@link ConstraintViolationException})
    • - *
- *

- * All error responses are formatted consistently using {@link BizExceptionResponse} to provide a - * uniform API error structure for client applications. + * This controller advise will catch some business exception which produced when performing actions. * * @author zihluwang + * @author siujamo * @see BizException * @see BizExceptionResponse * @see RestControllerAdvice diff --git a/src/main/java/com/onixbyte/helix/controller/MenuController.java b/src/main/java/com/onixbyte/helix/controller/MenuController.java index 4523651..ea260a6 100644 --- a/src/main/java/com/onixbyte/helix/controller/MenuController.java +++ b/src/main/java/com/onixbyte/helix/controller/MenuController.java @@ -10,6 +10,12 @@ import org.springframework.web.bind.annotation.RestController; import java.util.List; +/** + * This controller provides entry points to manipulate menus. + * + * @author zihluwang + * @author siujamo + */ @RestController @RequestMapping("/menus") public class MenuController { @@ -21,6 +27,11 @@ public class MenuController { this.menuService = menuService; } + /** + * Get menu tree. + * + * @return available menu tree for the current user + */ @GetMapping public List> getMenuTree() { return menuService.getMenuTree(); diff --git a/src/main/java/com/onixbyte/helix/controller/PositionController.java b/src/main/java/com/onixbyte/helix/controller/PositionController.java index 3ac6463..eb5cc06 100644 --- a/src/main/java/com/onixbyte/helix/controller/PositionController.java +++ b/src/main/java/com/onixbyte/helix/controller/PositionController.java @@ -11,6 +11,12 @@ import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; +/** + * This controller provides entry points to manipulate positions. + * + * @author zihluwang + * @author siujamo + */ @RestController @RequestMapping("/positions") public class PositionController { @@ -22,6 +28,13 @@ public class PositionController { this.positionService = positionService; } + /** + * Get position data paginated. + * + * @param pageNum current page num + * @param pageSize page size + * @return paginated position data + */ @GetMapping public Page getPositions( @RequestParam(required = false, defaultValue = "1") Integer pageNum, diff --git a/src/main/java/com/onixbyte/helix/controller/RoleController.java b/src/main/java/com/onixbyte/helix/controller/RoleController.java index adbf5c2..f24068d 100644 --- a/src/main/java/com/onixbyte/helix/controller/RoleController.java +++ b/src/main/java/com/onixbyte/helix/controller/RoleController.java @@ -13,6 +13,12 @@ import org.springframework.http.ResponseEntity; import org.springframework.validation.annotation.Validated; import org.springframework.web.bind.annotation.*; +/** + * This controller provides entry points to manipulate roles. + * + * @author zihluwang + * @author siujamo + */ @RestController @RequestMapping("/roles") public class RoleController { diff --git a/src/main/java/com/onixbyte/helix/controller/SettingController.java b/src/main/java/com/onixbyte/helix/controller/SettingController.java index 8adb7d3..06320c5 100644 --- a/src/main/java/com/onixbyte/helix/controller/SettingController.java +++ b/src/main/java/com/onixbyte/helix/controller/SettingController.java @@ -1,11 +1,14 @@ package com.onixbyte.helix.controller; -import com.onixbyte.helix.domain.entity.Setting; -import org.springframework.web.bind.annotation.GetMapping; -import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; +/** + * This controller provides entry points to manipulate settings. + * + * @author zihluwang + * @author siujamo + */ @RestController @RequestMapping public class SettingController { diff --git a/src/main/java/com/onixbyte/helix/controller/UserController.java b/src/main/java/com/onixbyte/helix/controller/UserController.java index 00f9743..642d31f 100644 --- a/src/main/java/com/onixbyte/helix/controller/UserController.java +++ b/src/main/java/com/onixbyte/helix/controller/UserController.java @@ -1,9 +1,10 @@ package com.onixbyte.helix.controller; import com.onixbyte.helix.domain.web.request.AddUserRequest; +import com.onixbyte.helix.domain.web.request.EditUserRequest; import com.onixbyte.helix.domain.web.request.QueryUserRequest; import com.onixbyte.helix.domain.web.request.ResetPasswordRequest; -import com.onixbyte.helix.domain.web.request.EditUserRequest; +import com.onixbyte.helix.domain.web.response.ActionResponse; import com.onixbyte.helix.domain.web.response.UserDetailResponse; import com.onixbyte.helix.service.UserService; import org.springframework.beans.factory.annotation.Autowired; @@ -15,6 +16,12 @@ import org.springframework.security.access.prepost.PreAuthorize; import org.springframework.validation.annotation.Validated; import org.springframework.web.bind.annotation.*; +/** + * This controller provides entry points to manipulate users. + * + * @author zihluwang + * @author siujamo + */ @RestController @RequestMapping("/users") public class UserController { @@ -56,29 +63,53 @@ public class UserController { return userService.getUserDetailByUserId(userId); } + /** + * Add a new user. + * + * @param request user to be added + * @return added user + */ @PostMapping @PreAuthorize("hasAnyAuthority('system:user:write')") public UserDetailResponse addUser(@Validated @RequestBody AddUserRequest request) { return userService.addUser(request); } + /** + * Edit a user. + * + * @param request user to be edited + * @return edited user + */ @PutMapping public ResponseEntity editUser(@Validated @RequestBody EditUserRequest request) { userService.updateUser(request); return ResponseEntity.ok(null); } + /** + * Reset user's password. + * + * @param request reset password request, contains ID of the user and new password + * @return action response + */ @PreAuthorize("hasAnyAuthority('system:user:reset-password')") @PatchMapping("/reset-password") - public ResponseEntity resetPassword(@Validated @RequestBody ResetPasswordRequest request) { + public ActionResponse resetPassword(@Validated @RequestBody ResetPasswordRequest request) { userService.resetPassword(request); - return ResponseEntity.ok(null); + return ActionResponse.success("密码修改成功"); } + /** + * Delete a user. + * + * @param userId ID of the user to be deleted + * @return action response + */ @PreAuthorize("hasAnyAuthority('system:user:write')") @DeleteMapping("/{userId:\\d+}") - public ResponseEntity deleteUser(@PathVariable Long userId) { + public ActionResponse deleteUser(@PathVariable Long userId) { userService.deleteUser(userId); - return ResponseEntity.ok(null); + return ActionResponse.success("删除成功"); } } diff --git a/src/main/java/com/onixbyte/helix/domain/web/response/ActionResponse.java b/src/main/java/com/onixbyte/helix/domain/web/response/ActionResponse.java new file mode 100644 index 0000000..8568960 --- /dev/null +++ b/src/main/java/com/onixbyte/helix/domain/web/response/ActionResponse.java @@ -0,0 +1,15 @@ +package com.onixbyte.helix.domain.web.response; + +public record ActionResponse( + String message, + boolean success +) { + + public static ActionResponse success(String message) { + return new ActionResponse(message, true); + } + + public static ActionResponse failed(String message) { + return new ActionResponse(message, false); + } +}