From eba4f078321e9df82a4cb97ffe37d2cae31d991b Mon Sep 17 00:00:00 2001
From: pigeon <zs@vifo.net>
Date: Sun, 7 Jun 2026 17:54:04 +0800
Subject: [PATCH] =?UTF-8?q?docs(standards):=20=E5=A2=9E=E5=8A=A0=20Feign?=
 =?UTF-8?q?=20=E5=AE=A2=E6=88=B7=E7=AB=AF=E6=B3=A8=E5=86=8C=E8=A7=84?=
 =?UTF-8?q?=E8=8C=83=E7=AB=A0=E8=8A=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

按用户提醒 + 本次实际踩坑记录：
- 项目用 rui-common-feign 自定义注册机制
- spring.factories 是 Feign 唯一注册渠道（@EnableFeignClients 包扫描不生效）
- 添加新 FeignClient 必须同步更新 spring.factories
- 漏写会导致运行时 NPE
---
 standards/coding-standards.md | 36 +++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/standards/coding-standards.md b/standards/coding-standards.md
index eb92bcf..b6b1015 100644
--- a/standards/coding-standards.md
+++ b/standards/coding-standards.md
@@ -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 必须遵守：