ai-engineering-init 1.7.0 → 1.10.0

package/.codex/skills/backend-annotations/SKILL.md

@@ -1,302 +1,248 @@
 ---
 name: backend-annotations
 description: |
-  后端高级注解使用指南。包含 @RateLimiter、@RepeatSubmit、@Sensitive、@EncryptField、@ApiEncrypt、@DataPermission 等注解的用法。
-
+  通用后端高级注解指南。包含限流、防重复提交、数据脱敏、字段加密、接口加密等横切关注点的 AOP 实现模式。
   触发场景：
-  - 配置接口限流（@RateLimiter）
-  - 配置防重复提交（@RepeatSubmit）
-  - 配置数据脱敏（@Sensitive）
-  - 配置字段加密（@EncryptField）
-  - 配置接口加密（@ApiEncrypt）
-  - 配置数据权限注解（@DataPermission）
-
-  触发词：注解、@RateLimiter、@RepeatSubmit、@Sensitive、@EncryptField、@ApiEncrypt、@DataPermission、@DataColumn、限流、防重复、脱敏、加密、数据权限注解
+  - 配置接口限流
+  - 配置防重复提交
+  - 配置数据脱敏
+  - 配置字段加密 / 接口加密
+  触发词：注解、限流、防重复提交、脱敏、加密、RateLimiter、Idempotent、Sensitive、Encrypt、AOP
+  注意：如果项目有专属技能（如 `leniu-backend-annotations`），优先使用专属版本。
 ---
 
-# 后端高级注解指南
+# 后端高级注解开发指南
 
-> RuoYi-Vue-Plus 三层架构，包名 `org.dromara.*`
+> 通用模板。如果项目有专属技能（如 `leniu-backend-annotations`），优先使用。
 
-## 注解总览
+## 设计原则
 
-| 注解 | 机制 | 作用层 | 依赖 |
-|------|------|--------|------|
-| `@RateLimiter` | AOP | Controller 方法 | Redis |
-| `@RepeatSubmit` | AOP | Controller 方法 | Redis + Token |
-| `@Sensitive` | Jackson 序列化器 | VO 字段 | 无 |
-| `@EncryptField` | MyBatis 拦截器 | Entity 字段 | 无 |
-| `@ApiEncrypt` | 拦截器 | Controller 方法 | 无 |
-| `@DataPermission` | AOP | Mapper 接口 | MyBatis |
+1. **横切关注点用 AOP**：限流、防重复、脱敏、加密属于非功能性需求，应通过注解 + AOP/拦截器实现，不侵入业务代码。
+2. **分层职责清晰**：限流/防重复作用于 Controller 层；脱敏作用于 VO 序列化层；加密作用于持久化层。
+3. **声明式优于编程式**：用注解声明意图，框架自动执行，减少样板代码。
+4. **配置外置**：密钥、阈值等参数放在配置文件或配置中心，不硬编码。
 
 ---
 
-## 1. @RateLimiter - 接口限流
+## 实现模式
 
-**导入**：`org.dromara.common.ratelimiter.annotation.RateLimiter`
+### 1. 接口限流
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `key` | String | "" | 限流key，支持SpEL |
-| `time` | int | 60 | 时间窗口（秒） |
-| `count` | int | 100 | 最大请求次数 |
-| `limitType` | LimitType | DEFAULT | DEFAULT/IP/CLUSTER |
-| `message` | String | 国际化key | 错误提示 |
+**概念**：通过 AOP 拦截请求，基于 Redis/内存计数器控制单位时间内的请求次数。
 
 ```java
-// 全局限流：60秒100次
-@RateLimiter(time = 60, count = 100)
-@GetMapping("/list")
-public R<List<XxxVo>> list() { }
-
-// IP限流：每个IP每分钟10次（登录、验证码）
-@RateLimiter(time = 60, count = 10, limitType = LimitType.IP)
-@PostMapping("/login")
-public R<String> login() { }
-
-// 动态key：基于用户ID限流
-@RateLimiter(key = "#userId", time = 60, count = 5)
-@PostMapping("/submit")
-public R<Void> submit(Long userId) { }
+// 自定义注解
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface RateLimiter {
+    String key() default "";          // 限流key，支持 SpEL
+    int time() default 60;            // 时间窗口（秒）
+    int count() default 100;          // 最大请求次数
+    LimitType limitType() default LimitType.DEFAULT; // DEFAULT / IP / CLUSTER
+    String message() default "请求过于频繁";
+}
+
+// AOP 切面
+@Aspect
+@Component
+public class RateLimiterAspect {
+
+    @Autowired
+    private StringRedisTemplate redisTemplate;
+
+    @Around("@annotation([你的包名].annotation.RateLimiter)")
+    public Object around(ProceedingJoinPoint point) throws Throwable {
+        RateLimiter limiter = /* 获取注解 */;
+        String key = buildKey(limiter, point);
+        // 使用 Redis Lua 脚本做原子计数
+        Long count = redisTemplate.execute(rateLimiterScript, List.of(key),
+            String.valueOf(limiter.count()), String.valueOf(limiter.time()));
+        if (count != null && count > limiter.count()) {
+            throw new [你的异常类](limiter.message());
+        }
+        return point.proceed();
+    }
+}
 ```
 
----
+**推荐阈值参考**：
 
-## 2. @RepeatSubmit - 防重复提交
+| 场景 | 时间窗口 | 次数 | 限流类型 |
+|------|---------|------|---------|
+| 登录接口 | 60s | 5-10 | IP |
+| 验证码 | 60s | 3 | IP |
+| 查询接口 | 60s | 100-1000 | DEFAULT |
+| 写入接口 | 60s | 10-50 | DEFAULT |
+| 敏感操作 | 60s | 1-5 | IP |
+
+---
 
-**导入**：`org.dromara.common.idempotent.annotation.RepeatSubmit`
+### 2. 防重复提交
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `interval` | int | 5000 | 间隔时间（毫秒） |
-| `timeUnit` | TimeUnit | MILLISECONDS | 时间单位 |
-| `message` | String | 国际化key | 错误提示 |
+**概念**：在指定时间窗口内，相同用户的相同请求（基于 Token + 参数哈希）只允许提交一次。
 
 ```java
-// 默认5秒
-@RepeatSubmit()
-@PostMapping()
-public R<Long> add(@RequestBody OrderBo bo) { }
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface RepeatSubmit {
+    int interval() default 5000;       // 间隔时间（毫秒）
+    TimeUnit timeUnit() default TimeUnit.MILLISECONDS;
+    String message() default "请勿重复提交";
+}
 
-// 10秒间隔 + 自定义提示
-@RepeatSubmit(interval = 10, timeUnit = TimeUnit.SECONDS, message = "请勿重复提交")
-@PostMapping("/pay")
-public R<Void> pay(@RequestBody PayBo bo) { }
+// AOP 切面核心逻辑
+// 1. 从请求中提取 Token + 请求参数
+// 2. 计算 MD5(token + ":" + serialize(params))
+// 3. Redis SETNX，设置过期时间 = interval
+// 4. 设置成功 -> 允许请求；设置失败 -> 拒绝
+// 5. 请求异常时删除 key，允许重试
 ```
 
-**原理**：`MD5(token + ":" + 序列化参数)` -> Redis 设置/检查 -> 成功保留key防重复 -> 异常删除key允许重试。
+| 场景 | 推荐间隔 |
+|------|---------|
+| 普通表单 | 3-5 秒 |
+| 订单创建 | 10 秒 |
+| 支付操作 | 30 秒 |
+| 文件上传 | 10 秒 |
 
 ---
 
-## 3. @Sensitive - 数据脱敏
+### 3. 数据脱敏
 
-**导入**：`org.dromara.common.sensitive.annotation.Sensitive`
+**概念**：在 JSON 序列化阶段，对 VO 中的敏感字段进行掩码处理。通过自定义 Jackson 序列化器实现。
 
-### 脱敏策略
+```java
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+@JacksonAnnotationsInside
+@JsonSerialize(using = SensitiveSerializer.class)
+public @interface Sensitive {
+    SensitiveStrategy strategy();
+    String[] roleKey() default {};    // 拥有这些角色可查看原文
+    String[] perms() default {};       // 拥有这些权限可查看原文
+}
 
-| 策略 | 效果 | 策略 | 效果 |
-|------|------|------|------|
-| `ID_CARD` | 110\*\*\*5431 | `PHONE` | 176\*\*\*\*5371 |
-| `EMAIL` | t\*\*@example.com | `BANK_CARD` | 6222\*\*\*2853 |
-| `CHINESE_NAME` | 张\* | `ADDRESS` | 北京市朝阳区\*\*\*\* |
-| `PASSWORD` | \*\*\*\*\*\* | `IPV4` | 192.\*.\*.\* |
-| `FIRST_MASK` | a\*\*\*\*\* | `CLEAR` | "" |
+public enum SensitiveStrategy {
+    ID_CARD(s -> s.substring(0, 3) + "***" + s.substring(s.length() - 4)),
+    PHONE(s -> s.substring(0, 3) + "****" + s.substring(s.length() - 4)),
+    EMAIL(s -> s.charAt(0) + "**@" + s.substring(s.indexOf('@') + 1)),
+    CHINESE_NAME(s -> s.charAt(0) + "*".repeat(s.length() - 1)),
+    BANK_CARD(s -> s.substring(0, 4) + "****" + s.substring(s.length() - 4)),
+    PASSWORD(s -> "******");
 
-```java
+    private final Function<String, String> desensitizer;
+    // constructor, getter...
+}
+
+// 使用
 public class UserVo {
-    // 所有人看脱敏数据
     @Sensitive(strategy = SensitiveStrategy.PHONE)
     private String phone;
 
-    // admin 角色可查看原数据
     @Sensitive(strategy = SensitiveStrategy.ID_CARD, roleKey = {"admin"})
     private String idCard;
-
-    // 需要权限才能看原数据
-    @Sensitive(strategy = SensitiveStrategy.EMAIL, perms = {"system:user:detail"})
-    private String email;
 }
 ```
 
-**权限逻辑**：roleKey 和 perms 都为空 = 全部脱敏；满足任一 roleKey **或** 任一 perms = 可查看原数据（OR 关系）。
+**权限逻辑**：roleKey 和 perms 都为空 = 全部脱敏；满足任一条件 = 可查看原文（OR 关系）。
 
 ---
 
-## 4. @EncryptField - 字段加密
-
-**导入**：`org.dromara.common.encrypt.annotation.EncryptField`
+### 4. 字段加密（持久层）
 
-| 算法 | 说明 | 算法 | 说明 |
-|------|------|------|------|
-| `BASE64` | 编码（低安全） | `AES` | 对称加密（推荐） |
-| `RSA` | 非对称（高安全） | `SM2` | 国密非对称 |
-| `SM4` | 国密对称 | | |
+**概念**：通过 MyBatis 拦截器/TypeHandler，在数据写入数据库时自动加密，读取时自动解密。对业务代码透明。
 
 ```java
-@Data
-@TableName("test_demo")
-public class TestDemo extends BaseEntity {
-    // AES 加密（使用 yml 全局秘钥）
-    @EncryptField(algorithm = AlgorithmType.AES)
-    private String phone;
-
-    // RSA 加密（指定公私钥）
-    @EncryptField(algorithm = AlgorithmType.RSA,
-                 privateKey = "MIICdQ...", publicKey = "MFkwEw...")
-    private String idCard;
-
-    // 使用 yml 默认配置
-    @EncryptField
-    private String secretField;
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface EncryptField {
+    AlgorithmType algorithm() default AlgorithmType.DEFAULT; // 使用全局配置
+    String password() default "";    // AES/SM4 密钥
+    String publicKey() default "";   // RSA/SM2 公钥
+    String privateKey() default "";  // RSA/SM2 私钥
 }
-```
-
-**配置**：
-
-```yaml
-mybatis-encryptor:
-  enable: false
-  algorithm: BASE64          # 默认算法
-  encode: BASE64             # 编码方式：BASE64 | HEX
-  password: your-secret-16   # AES/SM4 秘钥（16字符）
-  publicKey: MFwwDQ...       # RSA/SM2 公钥
-  privateKey: MIIBVAIBADANBg... # RSA/SM2 私钥
-```
-
----
-
-## 5. @ApiEncrypt - 接口加密
 
-**导入**：`org.dromara.common.encrypt.annotation.ApiEncrypt`
-
-```java
-// 加密响应数据
-@ApiEncrypt(response = true)
-@GetMapping("/{id}")
-public R<UserVo> getUser(@PathVariable Long id) { }
+public enum AlgorithmType {
+    DEFAULT, BASE64, AES, RSA, SM2, SM4
+}
 ```
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `response` | boolean | false | 是否加密响应 |
-
-**配置**：
+**配置示例**：
 
 ```yaml
-api-decrypt:
-  enabled: true
-  headerFlag: encrypt-key
-  publicKey: MFwwDQ...       # 响应加密公钥
-  privateKey: MIIBVAIBADANBg... # 请求解密私钥
+# [你的加密配置前缀]:
+encrypt:
+  enable: true
+  algorithm: AES
+  password: your-secret-key-16ch   # AES/SM4 密钥（16字符）
+  public-key: MFkwEw...            # RSA/SM2 公钥
+  private-key: MIIBVAIBADANBg...   # RSA/SM2 私钥
 ```
 
 ---
 
-## 6. @DataPermission - 数据权限
+### 5. 接口加密（传输层）
 
-**导入**：`org.dromara.common.mybatis.annotation.DataPermission`、`@DataColumn`
+**概念**：通过 Filter/Interceptor，对 HTTP 请求体自动解密、响应体自动加密。适用于前后端通信加密。
 
 ```java
-public interface OrderMapper extends BaseMapperPlus<Order, OrderVo> {
-
-    // 按部门+创建人隔离
-    @DataPermission({
-        @DataColumn(key = "deptName", value = "dept_id"),
-        @DataColumn(key = "userName", value = "create_by")
-    })
-    default Page<OrderVo> selectPageOrderList(Page<Order> page, Wrapper<Order> wrapper) {
-        return this.selectVoPage(page, wrapper);
-    }
-
-    // 使用表别名
-    @DataPermission({
-        @DataColumn(key = "deptName", value = "d.dept_id"),
-        @DataColumn(key = "userName", value = "u.create_by")
-    })
-    List<OrderVo> selectWithJoin(@Param(Constants.WRAPPER) Wrapper<Order> wrapper);
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ApiEncrypt {
+    boolean response() default false; // 是否加密响应
 }
-```
-
-**@DataColumn 参数**：
 
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `key` | "deptName" | 占位符关键字 |
-| `value` | "dept_id" | 替换的字段名 |
-| `permission` | "" | 拥有此权限则不过滤 |
-
-**权限范围**：全部数据 / 本部门 / 本部门及以下 / 仅本人 / 自定义。
+// 在 RequestBodyAdvice / ResponseBodyAdvice 中拦截处理
+// 或通过 Filter + HttpServletRequestWrapper 实现
+```
 
 ---
 
-## 七、组合使用
+## 选型建议
 
-```java
-// 接口防护：限流 + 防重复 + 日志
-@RateLimiter(time = 60, count = 10, limitType = LimitType.IP)
-@RepeatSubmit(interval = 10, timeUnit = TimeUnit.SECONDS)
-@Log(title = "订单", businessType = BusinessType.INSERT)
-@PostMapping()
-public R<Long> addOrder(@Validated @RequestBody OrderBo bo) { }
-```
+| 关注点 | 实现方式 | 作用层 | 依赖 |
+|--------|---------|--------|------|
+| 限流 | AOP + Redis Lua 脚本 | Controller | Redis |
+| 防重复 | AOP + Redis SETNX | Controller | Redis + Token |
+| 脱敏 | Jackson 自定义序列化器 | VO 字段 | 无 |
+| 字段加密 | MyBatis 拦截器 / TypeHandler | Entity 字段 | 加密库 |
+| 接口加密 | Filter / RequestBodyAdvice | Controller 方法 | 加密库 |
 
-```java
-// 数据保护分层：Entity 加密存储 + VO 脱敏展示
-@TableName("sys_user")
-public class SysUser extends TenantEntity {
-    @EncryptField(algorithm = AlgorithmType.AES)
-    private String phone;          // 存储时加密
-}
-
-public class UserVo {
-    @Sensitive(strategy = SensitiveStrategy.PHONE)
-    private String phone;          // 序列化时脱敏
-}
-```
+| 加密算法 | 类型 | 密钥要求 | 适用场景 |
+|---------|------|---------|---------|
+| BASE64 | 编码（非加密） | 无 | 简单混淆 |
+| AES | 对称加密 | 16/24/32 字节 | 通用加密（推荐） |
+| RSA | 非对称加密 | 公钥/私钥对 | 高安全场景 |
+| SM4 | 国密对称 | 16 字节 | 国密合规 |
+| SM2 | 国密非对称 | 公钥/私钥对 | 国密合规 |
 
 ---
 
-## 八、常见错误
+## 常见错误
 
 ```java
-// ❌ @RateLimiter 用在 Service 方法上（无效，只能 Controller）
+// 1. 限流/防重复注解放在 Service 方法上（无效，应在 Controller）
 @Service
 public class XxxService {
-    @RateLimiter(...)  // 无效！
+    @RateLimiter(...)  // 无效！AOP 通常只拦截 Controller
     public void doSomething() { }
 }
 
-// ❌ @DataPermission 未配置 @DataColumn
-@DataPermission  // 空注解无效！
-public interface UserMapper { }
-
-// ❌ @Sensitive 用在 Entity 上（应在 VO 上）
-// ❌ @EncryptField 用在 VO 上（应在 Entity 上）
-
-// ✅ @DataPermission 支持类级别 + 方法级别（方法覆盖类）
-@DataPermission({ @DataColumn(key = "deptName", value = "dept_id") })
-public interface UserMapper {
-    @DataPermission({ /* 方法级覆盖 */ })
-    List<UserVo> selectList();
-}
-```
-
----
+// 2. @Sensitive 用在 Entity 上（应在 VO 上，序列化时生效）
+// 3. @EncryptField 用在 VO 上（应在 Entity 上，持久化时生效）
 
-## 九、参考实现
+// 4. 加密密钥硬编码在注解中
+@EncryptField(password = "my-secret-key")  // 不安全
+// 应使用全局配置或环境变量
 
-| 类型 | 位置 |
-|------|------|
-| 限流示例 | `org.dromara.demo.controller.RedisRateLimiterController` |
-| 脱敏示例 | `org.dromara.demo.controller.TestSensitiveController` |
-| 加密示例 | `org.dromara.demo.domain.TestDemo` |
-| 数据权限 | `org.dromara.system.mapper.SysUserMapper` |
+// 5. 限流 key 设计不合理
+@RateLimiter(key = "")  // 所有用户共享限流
+// 应根据场景选择：用户维度 key="#userId"，IP 维度 limitType=IP
 
-**配置位置**：
-
-```
-application.yml:
-  mybatis-encryptor.*  → @EncryptField 全局配置
-  api-decrypt.*        → @ApiEncrypt 全局配置
-  spring.data.redis.*  → @RateLimiter/@RepeatSubmit 依赖
+// 6. 组合注解顺序不当
+// 推荐顺序：限流 -> 防重复 -> 权限 -> 日志
+@RateLimiter(time = 60, count = 10)
+@RepeatSubmit(interval = 5000)
+@PostMapping()
+public Result<?> add(@RequestBody XxxDTO dto) { }
 ```