docs: 精简 JavaDoc 注释
This commit is contained in:
Ray.Hao
@@ -29,9 +29,7 @@ import java.io.InputStreamReader;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
|
||||
/**
|
||||
* 图形验证码校验过滤器。
|
||||
* <p>
|
||||
* 归使用方，因为验证码规则（哪些接口需要验证码、验证码类型）因项目而异。
|
||||
* 图形验证码校验过滤器
|
||||
*/
|
||||
public class CaptchaValidationFilter extends OncePerRequestFilter {
|
||||
|
||||
|
||||
@@ -9,9 +9,7 @@ import jakarta.servlet.http.HttpServletRequest;
|
||||
import jakarta.servlet.http.HttpServletResponse;
|
||||
|
||||
/**
|
||||
* 无权限访问处理器。
|
||||
* <p>
|
||||
* 归使用方，因为 JSON 响应格式因项目而异。
|
||||
* 无权限访问处理器
|
||||
*
|
||||
* @author Ray.Hao
|
||||
* @since 2.0.0
|
||||
|
||||
@@ -14,9 +14,7 @@ import jakarta.servlet.http.HttpServletResponse;
|
||||
import java.io.IOException;
|
||||
|
||||
/**
|
||||
* 统一处理 Spring Security 认证失败响应。
|
||||
* <p>
|
||||
* 归使用方，因为 JSON 响应格式（Result 结构、错误码）因项目而异。
|
||||
* 统一处理 Spring Security 认证失败响应
|
||||
*
|
||||
* @author Ray.Hao
|
||||
* @since 2.0.0
|
||||
|
||||
@@ -57,10 +57,8 @@ public class RepeatSubmitAspect {
|
||||
|
||||
/**
|
||||
* 生成防重复提交锁的 key
|
||||
* <p>
|
||||
* key 由「用户标识 + 接口(method:URI) + 请求体哈希」组成：只有同一用户在同一接口提交
|
||||
* 完全相同的请求体才视为重复提交；若仅按 method:URI 生成，同一接口的不同提交
|
||||
* （如新增菜单与新增目录）会在窗口内被误判为重复。
|
||||
*
|
||||
* <p>请求体哈希用于区分同一接口的不同提交（如新增菜单与新增目录）</p>
|
||||
*/
|
||||
private String buildLockKey(ProceedingJoinPoint pjp) {
|
||||
HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder.getRequestAttributes()).getRequest();
|
||||
|
||||
@@ -2,8 +2,6 @@ package com.youlai.boot.common.constant;
|
||||
|
||||
/**
|
||||
* JWT Claims声明常量
|
||||
* <p>
|
||||
* JWT Claims 属于 Payload 的一部分，包含了一些实体（通常指的用户）的状态和额外的元数据。
|
||||
*
|
||||
* @author haoxr
|
||||
* @since 2023/11/24
|
||||
|
||||
@@ -17,7 +17,7 @@ import java.io.Serializable;
|
||||
* - 错误码后三位编号与 HTTP 状态码无关。
|
||||
* <p>
|
||||
* 说明：
|
||||
* - 本项目仅保留实际使用的错误码，并在 A/B/C 各保留少量示例，避免枚举无限膨胀。
|
||||
* - 本项目仅保留实际使用的错误码，A/B/C 各保留少量示例。
|
||||
* - 如需扩展业务错误码，建议在对应宏观分类下按场景划分号段并保持全局唯一。
|
||||
* <p>
|
||||
* 附表（节选）：错误码列表（示例/项目使用项）
|
||||
|
||||
@@ -17,12 +17,6 @@ import java.nio.file.StandardCopyOption;
|
||||
|
||||
/**
|
||||
* IP工具类
|
||||
* <p>
|
||||
* 获取客户端IP地址和IP地址对应的地理位置信息
|
||||
* <p>
|
||||
* 使用Nginx等反向代理软件， 则不能通过request.getRemoteAddr()获取IP地址
|
||||
* 如果使用了多级反向代理的话，X-Forwarded-For的值并不止一个，而是一串IP地址，X-Forwarded-For中第一个非unknown的有效IP字符串，则为真实IP地址
|
||||
* </p>
|
||||
*
|
||||
* @author Ray
|
||||
* @since 2.10.0
|
||||
|
||||
@@ -27,9 +27,6 @@ public class JacksonConfig {
|
||||
|
||||
/**
|
||||
* 全局 JsonMapper
|
||||
*
|
||||
* <p>由 Spring Boot 自动装配到 Jackson 相关的 HttpMessageConverter 中，作为全局 JSON 序列化/反序列化
|
||||
* 行为的唯一入口。</p>
|
||||
*/
|
||||
@Bean
|
||||
public JsonMapper objectMapper() {
|
||||
|
||||
@@ -36,10 +36,7 @@ import org.springframework.security.web.access.intercept.AuthorizationFilter;
|
||||
import jakarta.servlet.DispatcherType;
|
||||
|
||||
/**
|
||||
* Spring Security 配置类。
|
||||
* <p>
|
||||
* 归使用方（auth 模块），安全规则（放行路径、CORS、Provider 装配、响应格式）
|
||||
* 因项目而异，不应由框架层强制装配。
|
||||
* Spring Security 配置类
|
||||
*
|
||||
* @author Ray.Hao
|
||||
* @since 4.3.1
|
||||
|
||||
@@ -9,8 +9,7 @@ import lombok.Getter;
|
||||
/**
|
||||
* 表单状态枚举
|
||||
*
|
||||
* <p>正数为有效生命周期（草稿/已发布），-1 为退役态（已停用），
|
||||
* 与字典等模块"启停"语义（1/0）不同类，故独立定义</p>
|
||||
* <p>-1 为停用态，其余为正常生命周期</p>
|
||||
*
|
||||
* @author Ray.Hao
|
||||
* @since 4.8.0
|
||||
|
||||
@@ -89,9 +89,6 @@ public interface FormDefinitionService extends IService<FormDefinition> {
|
||||
/**
|
||||
* 按 formKey 获取公开表单的渲染规则（匿名接口）
|
||||
*
|
||||
* <p>公开访问总闸：仅 is_public=1 且已发布的表单可获取，
|
||||
* 否则视为不存在（分享链接立即失效，无需召回）</p>
|
||||
*
|
||||
* @param formKey 表单唯一标识
|
||||
* @return 表单渲染数据
|
||||
*/
|
||||
@@ -108,9 +105,6 @@ public interface FormDefinitionService extends IService<FormDefinition> {
|
||||
/**
|
||||
* 生成表单访问菜单并授权可见角色（幂等：已生成时更新原菜单）
|
||||
*
|
||||
* <p>菜单 component 指向通用承载页 dynamic-form/render，路由参数携带 formKey；
|
||||
* 角色授权沿 tree_path 补齐祖先目录，防止侧边栏构树出现孤儿节点</p>
|
||||
*
|
||||
* @param formId 表单ID
|
||||
* @param menuForm 菜单发布参数
|
||||
* @return 是否生成成功
|
||||
|
||||
@@ -92,9 +92,6 @@ public class FormDataServiceImpl extends ServiceImpl<FormDataMapper, FormData> i
|
||||
/**
|
||||
* 数据落库（登录/匿名提交共用）
|
||||
*
|
||||
* <p>后端基础校验（必填/类型）+ 字段白名单过滤：前端校验可被绕过，
|
||||
* 恶意构造的未声明字段不会入库；匿名提交 create_by 由字段填充器留空</p>
|
||||
*
|
||||
* @param form 表单定义
|
||||
* @param data 提交数据
|
||||
*/
|
||||
@@ -111,9 +108,6 @@ public class FormDataServiceImpl extends ServiceImpl<FormDataMapper, FormData> i
|
||||
/**
|
||||
* 公开表单按 formKey + IP 限流（固定窗口计数）
|
||||
*
|
||||
* <p>Redis 异常时 Fail-Open 放行，与 IpRateLimitFilter 策略一致：
|
||||
* 限流是防刷兜底而非业务正确性保障，不能因 Redis 抖动拒绝正常提交</p>
|
||||
*
|
||||
* @param formKey 表单唯一标识
|
||||
* @param ip 提交方 IP
|
||||
*/
|
||||
@@ -154,9 +148,6 @@ public class FormDataServiceImpl extends ServiceImpl<FormDataMapper, FormData> i
|
||||
/**
|
||||
* 获取表单数据详情（只读回显）
|
||||
*
|
||||
* <p>版本快照严格回显：优先按提交时版本加载规则快照，
|
||||
* 防止表单定义变更（字段删除/改名）导致历史数据回显漂移</p>
|
||||
*
|
||||
* @param dataId 数据ID
|
||||
*/
|
||||
@Override
|
||||
|
||||
@@ -109,8 +109,7 @@ public class FormDefinitionServiceImpl extends ServiceImpl<FormDefinitionMapper,
|
||||
/**
|
||||
* 修改表单定义
|
||||
*
|
||||
* <p>formKey 创建后不可修改；草稿态可修改元数据与规则，
|
||||
* 非草稿态仅可修改规则（元数据只读，防止已发布表单的语义漂移）</p>
|
||||
* <p>formKey 创建后不可修改；草稿态可修改元数据与规则，非草稿态仅可修改规则</p>
|
||||
*
|
||||
* @param id 表单ID
|
||||
* @param formData 表单定义表单数据
|
||||
@@ -262,8 +261,8 @@ public class FormDefinitionServiceImpl extends ServiceImpl<FormDefinitionMapper,
|
||||
/**
|
||||
* 按 formKey 获取公开表单的渲染规则（匿名接口）
|
||||
*
|
||||
* <p>不复用 {@link #getFormRender(String)} 的 Redis 缓存：缓存 VO 不含 isPublic，
|
||||
* 开关切换需额外失效逻辑；公开页非高频路径（IP 全局限流兜底），直查更简单可靠</p>
|
||||
* <p>仅返回已发布且 isPublic=1 的表单；直查库，不读 {@link #getFormRender(String)} 的
|
||||
* Redis 缓存——缓存 VO 不含 isPublic，命中会绕过公开开关校验</p>
|
||||
*
|
||||
* @param formKey 表单唯一标识
|
||||
*/
|
||||
@@ -311,9 +310,6 @@ public class FormDefinitionServiceImpl extends ServiceImpl<FormDefinitionMapper,
|
||||
/**
|
||||
* 生成表单访问菜单并授权可见角色
|
||||
*
|
||||
* <p>菜单 component 指向通用承载页 dynamic-form/render，路由参数携带 formKey，
|
||||
* 承载页从 route.meta.params 读取后按 formKey 加载渲染规则</p>
|
||||
*
|
||||
* @param formId 表单ID
|
||||
* @param menuForm 菜单发布参数
|
||||
*/
|
||||
@@ -380,14 +376,8 @@ public class FormDefinitionServiceImpl extends ServiceImpl<FormDefinitionMapper,
|
||||
/**
|
||||
* 确保默认挂载目录"表单中心"存在，不存在则创建
|
||||
*
|
||||
* <p>挂载位置："动态表单"目录下（顶级入口聚合，员工侧边栏为 动态表单 > 表单中心 > 各表单；
|
||||
* 管理菜单不授权给填写角色即不渲染，无需顶级分离）；
|
||||
* "动态表单"目录缺失时（未执行 form.sql 的环境）退化为顶级创建兜底</p>
|
||||
*
|
||||
* <p>懒创建而非 SQL 预置：预置空目录在侧边栏是点不开的孤菜单（无子路由不注册）；
|
||||
* 首个表单发布时才建目录，目录一出现就有子菜单</p>
|
||||
*
|
||||
* <p>踩坑：saveMenu 内部 saveOrUpdate 不回写表单对象主键，需按路由名称反查实体</p>
|
||||
* <p>挂到顶级"动态表单"目录下，该目录缺失时退化为顶级创建；
|
||||
* 无子菜单的目录在侧边栏不渲染</p>
|
||||
*
|
||||
* @return 默认目录实体
|
||||
*/
|
||||
|
||||
@@ -13,12 +13,8 @@ import java.util.Map;
|
||||
/**
|
||||
* 表单规则校验器（后端基础校验 + 字段白名单）
|
||||
*
|
||||
* <p>前端校验可被绕过，后端基于 form-create rule 的 validate 规则做兜底校验：
|
||||
* 必填（required）与基础类型（number/array），并按 rule 声明的 field 做白名单过滤，
|
||||
* 恶意构造的未声明字段不会入库</p>
|
||||
*
|
||||
* <p>仅做基础校验（与 rule validate 语义对齐），pattern/min/max 等复杂规则
|
||||
* 由前端 form-create 完整执行，后端不重复实现整套校验引擎</p>
|
||||
* <p>按 form-create rule 的 validate 声明校验必填（required）与基础类型（number/array），
|
||||
* 并按 rule 声明的 field 过滤数据</p>
|
||||
*
|
||||
* @author Ray.Hao
|
||||
* @since 4.8.0
|
||||
|
||||
@@ -111,7 +111,7 @@ public class AliyunFileServiceImpl implements FileService {
|
||||
/**
|
||||
* 获取文件访问主机地址（含协议），如 {@code https://bucket.oss-cn-hangzhou.aliyuncs.com}。
|
||||
* <p>
|
||||
* 协议以 endpoint 配置为准，未指定时默认 https；上传拼接 URL 与删除解析 URL 共用，保证两处口径一致。
|
||||
* 协议以 endpoint 配置为准，未指定时默认 https。
|
||||
*/
|
||||
private String getFileHost() {
|
||||
String endpointWithProtocol = endpointWithProtocol();
|
||||
|
||||
Reference in New Issue
Block a user