From 5bd69e7f1c113d8e205cc0b88bc5279317782039 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Fri, 30 Oct 2026 16:37:54 +0800 Subject: [PATCH] =?UTF-8?q?docs(guide):=20=E8=A1=A5=E5=85=85=E7=AB=AF?= =?UTF-8?q?=E7=82=B9=E5=86=99=E6=88=90=E5=B8=B8=E9=87=8F=E3=80=81SDK=20?= =?UTF-8?q?=E4=B8=8D=E7=A2=B0=E5=AD=98=E5=82=A8=E4=B8=8D=E8=AF=BB=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E4=B8=A4=E6=9D=A1=E7=BA=A6=E5=AE=9A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- GUIDE.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/GUIDE.md b/GUIDE.md index a8879ec..967f970 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -459,6 +459,23 @@ public final class AcmeOrderDto { 省掉全部样板;`core` 的模型是不可变 + Builder,本来就没有 setter,且 `core` 要尽量少依赖 编译期工具。Lombok 声明为 `scope=provided`,不进宿主运行时。 +**端点和路径写成常量,不做配置。** 协议细节(URL、字段名、限流值)是代码的一部分—— +配置化会让线上和测试跑不同协议,出问题无法从代码复现。`AdapterConfig` 不是配置项, +它只承载「测试时替换目标地址」这一种由调用方显式传入的参数。 + +```java +public final class AcmeConstants { + /** 生产基址;仅测试/联调时由 AdapterConfig 覆盖。 */ + public static final String DEFAULT_BASE_URL = "https://api.acme.example.com"; + public static final String PATH_TOKEN = "/oauth/token"; + public static final String PATH_ORDERS = "/v1/orders"; + public static final int MAX_PAGE_SIZE = 100; +} +``` + +**SDK 不碰存储、不读配置。** 账户、密钥、token、水位线、幂等记录全部经 SPI 由宿主提供; +适配器构造函数里只接收这些 SPI 与 `Clock`,不接收 `DataSource`、`Properties` 之类的对象。 + ### 第 4 步:Mapper —— DTO → 统一模型 ```java