java-coding-style/references/01-命名格式与注释.md

@@ -24,12 +24,53 @@
 - **必须**：服从项目 formatter、Checkstyle 或编辑器配置；不得因本文件偏好覆盖自动化格式规则。
 - **必须**：控制语句始终使用大括号；关键字与左括号间保留空格；运算符两侧保留空格。
 - **必须**：默认使用 4 空格缩进且不使用 Tab；项目 formatter 另有规定时从项目。
-- **推荐**：单行不超过 120 字符；import 和自动生成代码按工具配置处理。
+- **推荐**：单行不超过 120 字符；该限制是可读性上限，不是主动换行目标。import 和自动生成代码按工具配置处理。
 - **推荐**：新增方法原则上不超过 80 行，新增类原则上不超过 500 行。生成代码、声明型配置或框架限制可例外，但应说明原因。
 - **推荐**：方法保持聚焦，避免超过三层嵌套；优先使用卫语句、提取方法或清晰的布尔变量。
 - **必须**：避免魔法值、重复代码、过深嵌套和无业务价值的抽象。
 - **必须**：不要提交仅由全局换行、import 重排或格式化导致的无关 diff。
 
+### 换行策略
+
+- **必须**：采用紧凑优先原则。完整语句、方法签名或方法调用未超过项目行宽且保持清晰时，保留在同一行。
+- **必须**：不要为了形式对称、固定“一行一个参数”或提前规避行宽而主动拆行。
+- **必须**：方法声明、方法调用和构造器调用需要换行时，在不超过项目行宽的前提下保留尽可能多的完整参数；仅在参数本身复杂或项目格式化工具要求时采用“一行一个参数”。
+- **必须**：布尔表达式需要换行时，将每个完整条件作为一个视觉单元，并按 `&&` 或 `||` 对齐；不要拆开简短的 `Objects.equals`、判空或比较表达式的参数。
+- **推荐**：短方法链保留在同一行；长方法链需要换行时，每行保留一个语义完整的调用阶段。
+- **推荐**：仅在超过项目行宽、包含复杂 Lambda/匿名类/嵌套调用、需要突出语义阶段或格式化工具强制时换行。
+
+方法签名超过行宽时，优先紧凑续行：
+
+```java
+private boolean matchesRule(PmsProductDO product, ProductValidityRuleTypeEnum ruleType,
+                            LocalDateTime thresholdEndExclusive) {
+```
+
+避免对每个参数机械换行：
+
+```java
+private boolean matchesRule(
+        PmsProductDO product,
+        ProductValidityRuleTypeEnum ruleType,
+        LocalDateTime thresholdEndExclusive) {
+```
+
+布尔条件换行时，每个条件保持完整：
+
+```java
+return Objects.equals(product.getMerchantNature(), ProductAttributeConstant.MERCHANT_NATURE_MERCHANT)
+        && Objects.equals(product.getVerifyStatus(), ProductVerifyStatusEnum.VERIFIED.getCode())
+        && Objects.equals(product.getDeleteStatus(), DelStatusEnum.NOT_DELETED.getCode());
+```
+
+避免拆开单个简短条件：
+
+```java
+return Objects.equals(
+        product.getMerchantNature(),
+        ProductAttributeConstant.MERCHANT_NATURE_MERCHANT);
+```
+
 ## 导入
 
 - **必须**：禁止通配符导入。

java-coding-style/references/02-类型OOP与API设计.md

@@ -34,6 +34,7 @@
 ## API 与兼容性
 
 - **必须**：公共 API 明确输入校验、返回语义、错误模型、幂等性和副作用。
+- **必须**：单资源路径已经通过 `@PathVariable` 确定资源身份时，不得再使用可选查询参数表达另一套资源标识。不同标识的查询入口应拆分；若多个标识共同构成业务校验条件，应明确必填性、匹配规则和错误语义。
 - **必须**：新增重载时检查 `null`、lambda、自动装箱和可变参数是否造成调用歧义。
 - **必须**：修改 DTO、枚举、JSON 字段、RPC 签名或异常类型前评估调用方兼容性。
 - **推荐**：返回接口类型而非具体集合实现；不要泄漏 ORM 实体、框架上下文或内部异常。