docs(standards): 增加 Feign 客户端注册规范章节

按用户提醒 + 本次实际踩坑记录:
- 项目用 rui-common-feign 自定义注册机制
- spring.factories 是 Feign 唯一注册渠道(@EnableFeignClients 包扫描不生效)
- 添加新 FeignClient 必须同步更新 spring.factories
- 漏写会导致运行时 NPE
This commit is contained in:
2026-06-07 17:54:04 +08:00
parent 3395f69b42
commit eba4f07832
+36
View File
@@ -302,6 +302,42 @@ Closes #123
---
## 🌐 Feign 客户端注册规范
`rui-common-feign` 提供自定义 Feign 注册机制(`CloudFeignAutoConfiguration` +
`CustomFeignClientsRegistrar`),**与 Spring Cloud 默认的包扫描机制不同**。
### 注册渠道
所有 `@FeignClient` 接口**必须**列在 `META-INF/spring.factories` 中:
```properties
# rui-common-{module}/src/main/resources/META-INF/spring.factories
com.rui.common.feign.CloudFeignAutoConfiguration=\
com.rui.{module}.feign.YourFeignClient,\
com.rui.{module}.feign.AnotherFeignClient
```
### 为什么不能只靠包扫描
- 项目使用自定义的 `CustomFeignClientsRegistrar`**只有当 `@CloudEnableFeignClients`
注解存在时才会触发包扫描**
- 项目**零处**使用 `@CloudEnableFeignClients` 注解
- 因此 `spring.factories` 是项目 Feign 客户端的**唯一**注册渠道
### 添加新 FeignClient 步骤
1. 定义 `@FeignClient` 接口(带 `contextId` / `path` / `fallbackFactory`
2. **必须**在 `META-INF/spring.factories` 中追加类名
3. 漏写第 2 步 → Bean 未注册 → 运行时 NPE"no qualifying bean of type ..."
### ❌ 禁止
- 只定义 `@FeignClient` 接口但忘了列 `spring.factories`(最常见的坑)
- 期待 Spring Cloud 默认的包扫描会帮你发现(项目里不会)
---
## 📦 Result 返回规范
`com.rui.common.core.result.Result` 是统一的 API 响应封装。所有 controller 必须遵守: