企业官网建设流程全解析

阿里巴巴Java开发手册工程结构规约：二方库依赖的GAV命名、版本管理与Maven依赖仲裁实战

【免费下载链接】p3cAlibaba Java Coding Guidelines pmd implements and IDE plugin项目地址: https://gitcode.com/gh_mirrors/p3/p3c

导读

本文以《阿里巴巴Java开发手册》工程结构章节中的"二方库依赖"规约为核心，系统讲解企业内部二方库（集团内各事业部/兄弟团队发布、供业务系统复用的类库）从坐标定义、版本号管理、依赖引入、版本仲裁到发布维护的完整规范。结合本仓库（Alibaba Java Coding Guidelines 的开源实现 p3c，内含 p3c-pmd 规则引擎与 IntelliJ/Eclipse 插件）中真实 Maven 与 Gradle 工程文件，逐条展开 10 项强制、推荐、参考规约的实操要点，帮助读者掌握可落地、可验证的依赖治理方法：既能写出合规的 GAV 坐标与版本号，也能用dependency:resolve、dependency:tree排查依赖冲突，还能通过<dependencyManagement>与统一版本变量根治"同一个 jar 多个版本"的经典问题。

一、规约背景：什么是"二方库"，为什么需要专门约束

在《阿里巴巴Java开发手册》的术语体系中，二方库（Second Party Library）指公司内部、但由其他部门或兄弟团队维护并发布的公共类库——例如com.alibaba.dubbo这样的集团级基础组件；与之对应，一方库指自身项目的内部模块，三方库指来自 Maven 中央仓库等外部生态的开源依赖。

二方库是大型组织中代码复用的主要载体，但也是依赖冲突、版本漂移、发布不可追溯的高发区。正因如此，本规约从"使用方视角"（如何声明依赖、如何命名、如何升级）和"发布方视角"（如何精简依赖、如何保持稳定可追溯）两个方向同时作出约束，全文共 10 条，约束力度由"强制"到"推荐"再到"参考"逐级递减。

二、GAV 坐标命名规约（强制）

GAV 即 Maven 坐标三要素GroupId:ArtifactId:Version，是依赖的唯一标识。规约第 1 条强制要求：

1. GroupID格式：com.{公司/BU}.业务线.[子业务线]，最多 4 级。
   • {公司/BU}为 BU 一级，如alibaba、taobao、tmall、aliexpress；子业务线可选。
   • 正例：com.taobao.jstorm、com.alibaba.dubbo.register。
2. ArtifactID格式：产品线名-模块名，语义不重复、不遗漏，命名前先到中央仓库查证是否已被占用。
   • 正例：dubbo-client、fastjson-api、jstorm-tool。
3. Version：详细规定见下文版本号命名规约。

以本仓库自身的发布坐标为例，p3c-pmd/pom.xml 中声明了groupId = com.alibaba.p3c、artifactId = p3c-pmd、version = 2.1.1，完全符合"公司(BU).业务线 + 产品线名-模块名 + 语义化版本"的结构。其中p3c-pmd即"p3c 产品线的 pmd 规则引擎模块"，com.alibaba.p3c则由公司域com.alibaba加业务线p3c构成，是规约正例在真实工程中的直接体现。

三、版本号命名规约：主版本号.次版本号.修订号（强制）

二方库版本号必须采用主版本号.次版本号.修订号三段式（即语义化版本），每段的升级语义严格界定：

配套的强制细节还有两点：

• 起始版本号必须是1.0.0，而不是0.0.1。这要求二方库从第一次正式发布起就以完整语义化版本起步，避免 0.x 阶段语义模糊。
• 正式发布前必须去中央仓库查证，保证版本号有延续性，且正式版本号不允许覆盖升级。若当前版本为1.3.3，下一个合理版本只能是1.3.4、1.4.0或2.0.0这类递增版本，绝不允许重新发布同名旧版本号覆盖历史内容。

版本号的可追溯性还体现在仓库的依赖引用中：例如 idea-plugin/p3c-common/build.gradle 固定引用com.alibaba.p3c:p3c-pmd:2.1.0，eclipse-plugin/com.alibaba.smartfox.eclipse.plugin/pom.xml 固定引用com.alibaba.p3c:p3c-pmd:2.0.1，均为显式、确定的发布版本，便于回溯"当前构建基于哪个版本的规则引擎"。

四、线上应用禁止依赖 SNAPSHOT 版本（强制）

规约第 3 条强制：线上应用不要依赖 SNAPSHOT 版本（安全包除外）。原因有二：

1. 保证应用发布的幂等性：SNAPSHOT 版本内容可变，同一版本号在不同时间拉取可能得到不同代码，导致"今天构建能跑、明天构建出问题"的不可复现现象。
2. 加快编译时的打包构建：固定版本可以充分利用本地仓库缓存，减少对远端快照仓库的反复校验与拉取。

从源码证据看，本仓库对"快照仅用于开发链路"的边界划分非常清晰：

• eclipse-plugin/pom.xml 中父 POM 版本为2.0.1-SNAPSHOT（研发中），同时为快照依赖单独配置了sonatype-nexus-snapshots仓库，并显式设置<snapshots><enabled>true</enabled></snapshots>、<releases><enabled>false</enabled></releases>——即只有 SNAPSHOT 依赖才允许从该仓库解析；
• idea-plugin/p3c-common/build.gradle 中通过ext.isReleaseVersion = !version.endsWith("SNAPSHOT")区分发布版本，并分别配置repository（正式仓库）与snapshotRepository（快照仓库），签名插件也仅在正式发布时启用。

这组配置恰恰演示了正确姿势：SNAPSHOT 只允许出现在内部开发/快照仓库，正式发布与线上应用必须使用固定版本。

五、依赖升级不得破坏仲裁结果：dependency:resolve 与 dependency:tree（强制）

规约第 4 条强制：二方库的新增或升级，必须保持除功能点之外的其它 jar 包仲裁结果不变。若确有变化，必须明确评估和验证，并给出标准排查动作：

1. 升级前后分别执行dependency:resolve，比对依赖解析结果；
2. 若仲裁结果完全不一致，执行dependency:tree找出差异点；
3. 对不需要的传递依赖，通过<excludes>排除。

例如新增某个二方库后，它可能把log4j 1.2.15传递进来，与工程已有的log4j 1.2.17竞争仲裁，此时应在该依赖声明中排除传递版本：

<dependency> <groupId>com.example</groupId> <artifactId>some-lib</artifactId> <version>2.0.0</version> <exclusions> <exclusion> <groupId>log4j</groupId> <artifactId>log4j</artifactId> </exclusion> </exclusions> </dependency>

"保持仲裁结果不变"的意图在于：依赖变更只应带来功能增量，而不应悄悄改变其他第三方 jar 的解析版本，进而引发线上运行时行为突变。仓库中的依赖复制配置也体现了对"依赖边界"的精细控制——eclipse-plugin/com.alibaba.smartfox.eclipse.plugin/pom.xml 使用maven-dependency-plugin的copy-dependencies把依赖复制到target/lib，并通过excludeGroupIds（如p2.eclipse-plugin,apex）与excludeArtifactIds明确剔除不必要的传递依赖，正是"只引入所需、显式管控依赖集合"的工程化落地。

六、接口返回值的枚举边界（强制）

规约第 5 条强制：二方库里可以定义枚举类型，参数可以使用枚举类型，但是接口返回值不允许使用枚举类型或者包含枚举类型的 POJO 对象。

其本质是 API 的向后兼容性设计：枚举一旦作为返回值暴露，新增枚举值对调用方是源码兼容但二进制/运行时潜在不兼容的变更（调用方 switch 未覆盖新值时可能落入默认分支或抛异常）；而参数中的枚举因为由调用方显式构造，可控性更高。发布方应尽量以稳定类型（如字符串、数值及文档化的取值表）作为返回值，把枚举的演进风险隔离在二方库内部。

七、统一版本变量，避免版本号漂移（强制）

规约第 6 条强制：依赖于一个二方库群时，必须定义一个统一的版本变量，避免版本号不一致。

典型场景是 Spring 全家桶：springframework-core、springframework-context、springframework-beans属于同一发布节奏，必须使用同一个版本。做法是先在<properties>中定义变量：

<properties> <spring.version>4.3.18.RELEASE</spring.version> </properties>

再在各依赖声明中引用该变量：

<dependency> <groupId>org.springframework</groupId> <artifactId>spring-core</artifactId> <version>${spring.version}</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-context</artifactId> <version>${spring.version}</version> </dependency> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-beans</artifactId> <version>${spring.version}</version> </dependency>

本仓库对此有极为典型的实证：p3c-pmd/pom.xml 在<properties>中定义了pmd.version=6.15.0、kotlin.version=1.3.72、annotation.version=1.3.2三个版本变量，随后pmd-java、pmd-vm、pmd-test三个同族依赖全部引用${pmd.version}，kotlin-stdlib-jdk8引用${kotlin.version}，javax.annotation-api引用${annotation.version}。任何一个变量只需改一处，全族依赖的版本即可同步升级，从根本上杜绝"core 是 6.15.0、vm 却是 6.14.0"的错位。

八、子项目禁止出现同坐标不同版本（强制）

规约第 7 条强制：禁止在子项目的 pom 依赖中出现相同的 GroupId、相同的 ArtifactId，但不同的 Version。

规约给出的原因是经典的"多模块聚合发布"陷阱：本地调试时，各子项目可以使用各自声明的版本号，各自都能编译运行；但多模块合并打包成 WAR 后，lib目录中同一个 jar 只能保留一个版本。于是可能出现"线下调试完全正确，发布到线上却因版本被仲裁覆盖而故障"的问题。解决办法是：子项目一律不写版本号，版本统一由父 POM 的<dependencyManagement>仲裁（详见下一节）。

九、dependencies 与 dependencyManagement 职责分离（推荐）

规约第 8 条推荐：所有 pom 文件中的依赖声明放在<dependencies>语句块中，所有版本仲裁放在<dependencyManagement>语句块中，并明确了两者的行为差异：

• <dependencyManagement>：只声明版本，不实现引入。子项目需要显式声明依赖，version和scope都读取自父 POM。因此父 POM 在此处集中锁定版本，子模块各自按需声明依赖但不必（也不允许）再写版本号。
• <dependencies>：所有声明在主 POM 的依赖都会自动引入，并被所有子项目默认继承。因此主 POM 的<dependencies>只应放所有子模块都真正需要的公共依赖（如统一的测试框架、日志门面），避免无关依赖被无条件传导。

仓库中 eclipse-plugin/pom.xml 正是这一模式的示范：<dependencies>中只放子模块共享的junit 4.11（test scope），而<dependencyManagement>中集中管理kotlin-stdlib-jdk8的版本（引用${kotlin.version}变量）；真正需要 Kotlin 运行库的子模块则在各自 POM 的<dependencies>中显式声明、不写版本号，由父 POM 仲裁。这保证了多模块（plugin/feature/updatesite 三个子模块）之间不会出现 Kotlin 版本漂移。

十、二方库应尽量减少配置项（推荐）

规约第 9 条推荐：二方库不要有配置项，最低限度不要再增加配置项。

理由在于：每个配置项都是使用方的认知负担与故障面。配置项越多，使用方越容易配错、越难以理解默认行为，且二方库内部配置的读取时机（静态初始化、Spring 装配等）往往隐藏时序陷阱。设计上应优先"零配置即用"，把可变行为收敛为方法参数或默认值；确有必要时，也应以极简、自解释、向后兼容的方式提供，并配套完整文档。

十一、发布方原则：精简可控与稳定可追溯（参考）

规约第 10 条从二方库发布者视角给出两条参考原则：

1）精简可控原则。二方库应只包含必要的 Service API、领域模型对象、Utils 类、常量、枚举等，移除一切不必要的 API 和依赖。具体手段包括：

• 依赖其它二方库时，尽量使用providedscope 引入，把具体版本号的选择权留给二方库使用者，避免版本仲裁的连锁影响；
• 不绑定具体日志实现，只依赖日志框架（如slf4j-api），由使用方决定日志后端。

2）稳定可追溯原则。每个版本的变化都应被记录，二方库由谁维护、源码在哪里，都要能方便查到；除非用户主动升级版本，否则公共二方库的行为不应发生变化。这条原则实际上要求发布方建立 CHANGELOG、维护者名单与源码地址的完整配套。

本仓库作为一个真实发布的二方库（com.alibaba.p3c:p3c-pmd），其工程配置可视为这两条原则的注脚：发布配置中完整声明了licenses（Apache 2.0）、scm（源码仓库地址）、developers（维护者姓名与邮箱）等元信息，并配置了maven-javadoc-plugin（生成 API 文档）、maven-gpg-plugin（签名）与maven-assembly-plugin（打包可执行分发物）——详见 p3c-pmd/pom.xml；IntelliJ 侧的公共模块 idea-plugin/p3c-common/build.gradle 同样声明了pom.project下的 name、description、scm、licenses、developers 全套发布元数据。这正是"版本可查、归属可查、源码可查"的工程化保障。

十二、规约速查总表

结语

二方库依赖规约的实质，是把"坐标可识别、版本可演进、仲裁可预期、行为可追溯"四件事变成组织级的默认约定。对于使用方，掌握 GAV 命名、语义化版本、SNAPSHOT 隔离、统一版本变量与dependencyManagement职责分离，就能在日常开发中提前规避绝大多数依赖冲突；对于发布方，遵循精简可控与稳定可追溯原则，则能让每个版本都经得起下游系统的长期依赖。本文所述规则来自 p3c-gitbook/工程结构/二方库依赖.md，并结合 p3c 仓库自身的 Maven/Gradle 工程配置（p3c-pmd/pom.xml、eclipse-plugin/pom.xml、idea-plugin/p3c-common/build.gradle 等）做了源码级印证，读者可对照这些真实文件加深理解。

【免费下载链接】p3cAlibaba Java Coding Guidelines pmd implements and IDE plugin项目地址: https://gitcode.com/gh_mirrors/p3/p3c