3. 服务端SDK依赖配置与版本管理

支付SDK接入的第一步是正确引入依赖并管理版本。不同语言生态（Java、Node.js）依赖声明、锁定、仓库配置和冲突排查的方式各有差异，但核心原则一致：可重复、可追溯、无冲突。本章以Maven、Gradle、NPM三种主流工具为例，详解从依赖引入到生产部署的全流程。

3.1 依赖引入方式对比

3.2 具体配置示例

3.2.1 Maven（pom.xml）

<dependencies>
    <dependency>
        <groupId>com.example.payment</groupId>
        <artifactId>payment-sdk</artifactId>
        <version>2.1.4-RELEASE</version>
    </dependency>
</dependencies>

<!-- 版本锁定 —— 防止传递依赖替换版本 -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.example.payment</groupId>
            <artifactId>payment-sdk</artifactId>
            <version>2.1.4-RELEASE</version>
        </dependency>
    </dependencies>
</dependencyManagement>

3.2.2 Gradle（build.gradle）

dependencies {
    implementation 'com.example.payment:payment-sdk:2.1.4-RELEASE'
}

// 版本强制锁定
configurations.all {
    resolutionStrategy {
        force 'com.example.payment:payment-sdk:2.1.4-RELEASE'
    }
}

3.2.3 npm（package.json）

{
  "dependencies": {
    "payment-sdk": "^2.1.4"
  },
  "overrides": {               // npm v8+ 版本锁定
    "payment-sdk": "2.1.4"
  }
}

3.3 仓库镜像配置

国内访问中央仓库缓慢，必须配置镜像以提升构建稳定性。以下为常用镜像配置：

<!-- Maven settings.xml mirror -->
<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <mirrorOf>*</mirrorOf>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
</mirrors>

// Gradle repositories 块
repositories {
    maven { url 'https://maven.aliyun.com/repository/public' }
    mavenCentral()
}

// .npmrc 配置
registry=https://registry.npmmirror.com

3.4 依赖冲突排查方法

支付SDK常依赖HTTP客户端（OkHttp、Apache HttpClient）、JSON解析库（Jackson、Gson）等，当项目中已有不同版本时可能触发冲突。排查步骤：

1. 查看依赖树

# Maven
mvn dependency:tree -Dincludes=com.example.payment:payment-sdk

# Gradle
gradle dependencies --configuration runtimeClasspath

# npm
npm ls payment-sdk

2. 识别冲突版本：Maven显示omitted for conflict，Gradle显示-> version 2.1.4，npm显示多个版本。
3. 排除传递依赖

<!-- Maven 排除 -->
<dependency>
    <groupId>com.example.payment</groupId>
    <artifactId>payment-sdk</artifactId>
    <version>2.1.4-RELEASE</version>
    <exclusions>
        <exclusion>
            <groupId>com.squareup.okhttp3</groupId>
            <artifactId>okhttp</artifactId>
        </exclusion>
    </exclusions>
</dependency>

// Gradle 排除
implementation('com.example.payment:payment-sdk:2.1.4-RELEASE') {
    exclude group: 'com.squareup.okhttp3', module: 'okhttp'
}

// npm：package.json
{
  "overrides": {
    "okhttp": "4.11.0"
  }
}

3.5 依赖管理流程总览

下图梳理了从依赖引入到冲突排查的完整生命周期：

3.6 常见错误与排查清单