---
globs: ["**/gateway/**", "**/filter/**", "**/config/**", "**/interceptor/**", "**/*DTO.java", "**/*Req.java"]
---

# 网关使用规范

## 网关核心功能
- 请求鉴权：验证用户身份和权限
- 请求改写：自动将用户信息注入请求体
- 安全防护：黑白名单、攻击拦截
- 流量控制：限流和熔断机制

## 配置流程
1. 路由配置：配置网关路径标识和目标服务名称（与 Nacos 注册名一致）
2. 参数映射配置：设置参数映射规则，将 userId 和 companyId 重写到请求体

## 用户上下文获取机制
- 客户端在 Header 携带 token：`Authorization: Bearer {token}`
- 网关鉴权通过后，自动将 `userId` 和 `companyId` 注入请求体 JSON 中
- **用户信息从请求体（RequestBody）获取，不从请求头获取**
- **客户端不需要传递 userId 和 companyId，只需传递 token**
- 参数名称可根据网关配置自定义

## 后端代码编写指引
- DTO 中必须包含 `userId` 和 `companyId` 字段以接收网关注入的用户信息
- POST 接口使用 `@RequestBody` 接收包含用户信息的请求体

```java
// DTO 定义：包含网关注入字段
public class RequestDTO {
    private String userId;      // 网关自动注入
    private String companyId;   // 网关自动注入
    private String otherParam;  // 客户端传递
}

// Controller 接收
@PostMapping("/api/resource")
public ResponseEntity<?> processResource(@RequestBody RequestDTO request) {
    String userId = request.getUserId();       // 从请求体获取
    String companyId = request.getCompanyId();  // 从请求体获取
}
```

## 特殊场景处理
- 网关可能使用不同命名风格，通过 `@JsonProperty` 适配：
  ```java
  @JsonProperty("user_id")
  private String userId;
  ```
- 网关可能使用嵌套结构注入用户信息

## 常见错误模式
- ❌ 从 HttpServletRequest Header 中获取 userId → ✅ 从 RequestBody 获取
- ❌ 客户端传递 userId/companyId 参数 → ✅ 仅传递 token，用户信息由网关注入
- ❌ DTO 中缺少 userId/companyId 字段 → ✅ 所有需鉴权的接口 DTO 必须包含这两个字段