From 55a669b0ab7a806df27ae2947677b3d989f84f23 Mon Sep 17 00:00:00 2001 From: Xiang Date: Mon, 3 Aug 2026 15:40:32 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=E4=BC=98=E5=8C=96java=E4=BB=A3=E7=A0=81?= =?UTF-8?q?=E9=A3=8E=E6=A0=BC-=E6=8D=A2=E8=A1=8C=E7=AD=96=E7=95=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- java-coding-style/.DS_Store | Bin 0 -> 6148 bytes .../references/01-命名格式与注释.md | 43 +++++++++++++++++- .../references/02-类型OOP与API设计.md | 1 + vibe-coding-governance/.DS_Store | Bin 0 -> 6148 bytes vibe-coding-governance/assets/.DS_Store | Bin 0 -> 6148 bytes vue-coding-style/.DS_Store | Bin 0 -> 6148 bytes 6 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 java-coding-style/.DS_Store create mode 100644 vibe-coding-governance/.DS_Store create mode 100644 vibe-coding-governance/assets/.DS_Store create mode 100644 vue-coding-style/.DS_Store diff --git a/java-coding-style/.DS_Store b/java-coding-style/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..bd7e53d3a89de68cb3f5efed133e852da11ae093 GIT binary patch literal 6148 zcmeHK!A=4(5S;?TA~E5h3CAX0NklQI@v=eu0oUk34eko!#cMx~QXUpt-I&Ae?oI{?6%!_F>182}tq!b}l|1w#9zbCNNZ93oTCNFWYIaX*M; zFz0OzzmWm@c6soj2VD>_`~BX6eiX(@t@h3`+1y&b;1ryabK^b8k(c<%FmC#TD_WgP z83oh1A6$gpQMys)UAMMque81k9Op4Cd_RjHH`!RYF@{uuuEA8J4hLqM4`$xXOozhM z+wu8axdU@G+R-v#8JJ}ttCwY}|EJ6Q|JfkBvJ6-T{uKi(*Ya9TOv%*Nx#XzUa@1Q? q67owmeum&gm16XzQd~h*f_6?5MAu-d5iKb8M?leF2g|^ZGVlR{p^Yy9 literal 0 HcmV?d00001 diff --git a/java-coding-style/references/01-命名格式与注释.md b/java-coding-style/references/01-命名格式与注释.md index f9b2ebc..11e6a07 100644 --- a/java-coding-style/references/01-命名格式与注释.md +++ b/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); +``` + ## 导入 - **必须**：禁止通配符导入。 diff --git a/java-coding-style/references/02-类型OOP与API设计.md b/java-coding-style/references/02-类型OOP与API设计.md index 48f357d..41a1c0e 100644 --- a/java-coding-style/references/02-类型OOP与API设计.md +++ b/java-coding-style/references/02-类型OOP与API设计.md @@ -34,6 +34,7 @@ ## API 与兼容性 - **必须**：公共 API 明确输入校验、返回语义、错误模型、幂等性和副作用。 +- **必须**：单资源路径已经通过 `@PathVariable` 确定资源身份时，不得再使用可选查询参数表达另一套资源标识。不同标识的查询入口应拆分；若多个标识共同构成业务校验条件，应明确必填性、匹配规则和错误语义。 - **必须**：新增重载时检查 `null`、lambda、自动装箱和可变参数是否造成调用歧义。 - **必须**：修改 DTO、枚举、JSON 字段、RPC 签名或异常类型前评估调用方兼容性。 - **推荐**：返回接口类型而非具体集合实现；不要泄漏 ORM 实体、框架上下文或内部异常。 diff --git a/vibe-coding-governance/.DS_Store b/vibe-coding-governance/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..37de5ac8e3f45edd9195e0bfe1158ba285692b4d GIT binary patch literal 6148 zcmeHK%}&EG40d2_9SCU$kT^!-I*Gv$KjKmicmayw0BE$VKt)N=+Ofklsb_d0o`mPY zPBKIpToE99vcJTMTlw1(&j27ggWfto0{}c!!pc0FFND@fr)0)?s))ioBZn*+W)D%S zqp98OU0w6?R4+5JfnD(GUcK8`8I9Uo z+fCWtX^)$7w7b!2%FXuHcwG0ESJ(EAx_9Zl(odE|fp?CPMTZl3#z85k$DprLt!~gy zF|?N9C;n&ozUTBQ-+Aa`uGgr93a-$8yr=*2_xxpUpYoslE*Q%Uxbx#Jl-)dI2ABb6 zz|=~KJkUMiJ1i`ks{@T`0T3(bHiBd7B`8KZ^c@x!aRo)#P(&LlT#F%WIQpgA=Q}Jc z+HerA`4H~S!gVOZyd9q}&2|vJMYhZUGf-w=)=nE#{|~?K|I0xra81$x(RWx_L=Ou85im5cVFrGbfj4f) B%KiWV literal 0 HcmV?d00001 diff --git a/vibe-coding-governance/assets/.DS_Store b/vibe-coding-governance/assets/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..e3dfb9303664334ddedceaf5199865341bb8119d GIT binary patch literal 6148 zcmeHKPfNov6i>G4T86NL!j1v21E-Uzcqw&$0V{e?nJpb!?3%H5_AmxL>lgBq_<4LU zNyV`VogQs|u$QMl~hd)ormcbHUp|fIT&)y`7W%2;t zGPBGeBnF59VqjeuFz27uSeFIUI*9>d;KvN$`5-_M9fO5Nb#y?3*GKf%5K*9yZwW+U z&@otO1P=(;sen3_n>0lQo&M{bM)ai_?nc+KTW^P_6T+I%4p~4w=G*U|p5Ce-0 zRQ0fl_5b|)_y1xNjfeqa;9oJoYkjZp!jepFU0NL0S^;_wih^;4#?KV!s8S5ESc+Sq aO296#1LznmG=c?$E&_@MYKVbfW#9v8qfL$g literal 0 HcmV?d00001 diff --git a/vue-coding-style/.DS_Store b/vue-coding-style/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..80f47bd408222c48832b4082f3d61b7671f9bce5 GIT binary patch literal 6148 zcmeHKPfNov6i>G4T8Ges!j1v21E-a#cqwy!0V{e?nX9c@tj%aQcNl}7^$Yn){5-yw zWa8L7coA{$!OJgse;V>j$x9exygdwe7;_k77ARuLhGv1FA9YSj#)8PzH!>Enl-)v` z&qb5rFEW68x5jYa?m)lnUogu1K_Ub2zXkmy&IirrJ1>Ta$@xZEkHJopv9Sr&PXZLOJ|EgM~)0fY3!i(LfC`@T&}b0Co0F!~g&Q literal 0 HcmV?d00001 -- 2.54.0 From b65996538a628a348292fc4434002793e23f1094 Mon Sep 17 00:00:00 2001 From: Xiang Date: Mon, 3 Aug 2026 15:41:57 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=E5=BC=95=E5=85=A5gitignore?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2ceb563 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +### Mac ### +.DS_Store +*/.DS_Store \ No newline at end of file -- 2.54.0