这两天在跟 osSupplement/page 这个接口。它是审核后台里「补充资料」列表的数据源,链路不算长:请求进来先到 crm-admin(7011),crm-admin 自己不查库,转手交给 merchant-digital(18080),digital 查完再一层层包回去。
问题是我读代码时常常卡在词上——不是不懂 Spring 或 MyBatis,而是一个词在这条链路上到底指哪一段,说不清楚。于是把沿途遇到的词逐个整理成了一份术语表,存进博客:
👉 打开术语表:osSupplement/page 接口术语表
单文件 HTML,无外部依赖,双击就能在浏览器里打开,手机上也能看。
每条三行
这份表的结构很简单,每个词三行:
第三行是重点。只给定义的话,Feign 就是「伪装成普通接口的 HTTP 客户端」——这句话背得下来,但下次看到 OsSupplementInterface 还是不知道该往哪想。写成「让 crm-admin 像调本地方法一样调 digital 的 /v1/os/supplement/page」,就知道该去 kpay-merchant-digital-sdk 那个依赖里找声明了。
一共 126 条,按层面分成六组:
页面支持点任意一条复制,也可以整组复制、全部复制,方便粘到别处去问人或写注释。
这次真正搞明白的几条
一、/api 前缀不是应用加的。
代码里只能看到 /v1/osSupplement/page,浏览器里却是 /api/v1/...。我一开始以为是 context-path 配的,翻完 application.yml 发现 crm-admin 根本没配它。那这层只能来自网关——网关加上 /api,转发时再去掉,所以应用侧永远看不见。
这条推理链本身比结论有用:一个前缀消失,就一定能反推出是谁吃掉了它。
二、驼峰和斜杠分层,是两个不同的接口。
crm-admin 的路径是 /v1/osSupplement/page(驼峰),digital 的路径是 /v1/os/supplement/page(斜杠分层)。一开始我以为后者是前者的「规范化写法」,实际上它们毫无关系——一个是 gateway 暴露给前端的地址,一个是 digital 内部服务的地址。搞混了就会去 digital 的 Controller 里找 /v1/osSupplement,然后找不到。
三、两个同名的 OsSupplementPageRequest 是两个类。
crm-admin 里有一个,digital 里也有一个,字段差不多。它们的包名不同(crm.base 与 merchant.digital),所以是完全无关的两个类。改了一个没改另一个,接口不会报错——只会静默地少一个筛选条件。
四、page 其实是 offset。
前端传的 page=10,后端拿到的偏移量就是 10;page=10, rows=10 是第二页,不是第十页。这个字段名起得有迷惑性,但页面上写着 LIMIT 10 OFFSET 0,从这条 SQL 反推才对得上。第 0 页和第 1 页的区别,就在这里。
五、成功码是 10000,不是 200。
HTTP 状态码和业务状态码是两套东西。Wrapper.code 成功时是 10000,前端只看它。而且 message 成功时是 null——不能用「有没有 message」判断成败,必须看 code。
六、筛选为什么用 EXISTS 而不是 JOIN。
补件单对一个企业可能有多行子单(企业、店铺、商户各一条),直接 JOIN 会把主表行数放大,count 跟着翻倍,分页就乱了。所以筛店铺、筛商户、筛状态一律写成 EXISTS 子查询——只要子查询能查到至少一行就成立,不产生额外的行。
需要「把多个店铺编号拼成一个字段」时,用 string_agg 配合 GROUP BY company_id,回 Java 再拆开。这也是手册里那句「聚合函数是为了不打乱分页」的意思。
七、N+1 的具体形态。
列表一页 10 行,每行都要显示负责销售的姓名。库里的 shop 表只存账号 ID,如果一边遍历一边查账号服务,就是 1 次主查询 + 10 次子查询。做法是先把本页所有账号 ID 收进 LinkedHashSet 去重,再 getByIds(ids) 一次查回,装进 Map<账号ID, 姓名> 里回填。
一点体会
写这份表的过程,比表本身有用。
以前遇到生词,习惯是搜一下、看懂定义、继续往下读。问题是定义是对的,位置是错的——知道 Feign 是声明式 HTTP 客户端,不等于知道在这个仓库里该看哪个文件。术语表逼着我把每个词的第三行写出来,写不出来就说明还没真懂。
另一个意外收获是:这几组词之间是有依赖顺序的。先搞清「请求与网络」,才知道 /api 那层前缀去了哪;先搞清「Spring 分层」,才知道 Controller 不写业务、Service 才是流程;先搞清「响应结构」,才看得懂 Wrapper<PageData<T>> 里那两层包装各包着什么。
所以表里虽然分了六组,实际读的时候是一层层往里走的:从地址栏进到网关,进到 Controller,进到 Service,进到 Mapper,最后落到两条 SQL。
还有一点。这份表里有好几个词,我是先看到代码里的写法,回头才补上定义——比如 @QueryMap 是先把 DTO 的字段拼成了 ?a=1&b=2,才反应过来「哦,这就是把对象当查询参数用」。这个顺序和上学时相反,但记得牢得多。先有一个具体的问题,再去补对应的概念,大概就是上个月读到的那篇《为什么在今天,学习反而更重要了》里说的「按需式学习」——只不过后面还得跟一句:补完概念,最好留一份这样的表,否则下次还得从头找一遍。