3. 可复用开发套件设计原则

说实话，SDK 开发的第一步往往最容易被忽视。很多人觉得「装个环境嘛，谁不会？」但我在实际项目中见过太多因为环境不一致导致的诡异问题——本地能编译，CI 上就挂；同事机器跑得飞快，到你这就卡死。嗯，这一章咱们就把这事彻底理清楚。

3.1 语言环境配置：别小看版本管理

我个人习惯，不管用哪种语言，第一件事就是装版本管理工具。为什么？因为 SDK 要兼容不同用户的环境，你总不能在 README 里写「请使用 Python 3.8.5，其他版本不保证能用」吧？

3.1.1 Python：pyenv + virtualenv

Python 的版本管理，我推荐 pyenv。它能在系统层面管理多个 Python 版本，切换起来非常干净。

# 安装 pyenv（macOS/Linux）
curl https://pyenv.run | bash

# 安装指定 Python 版本
pyenv install 3.10.12

# 设置全局版本
pyenv global 3.10.12

# 验证
python --version  # 输出：Python 3.10.12

项目级隔离用 virtualenv 或 venv。我一般这样初始化：

# 创建虚拟环境
python -m venv .venv

# 激活（Linux/macOS）
source .venv/bin/activate

# 激活（Windows）
.venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

3.1.2 Java：JDK 版本 + SDKMAN

Java 的版本管理，我用 SDKMAN。它不仅能管理 JDK，还能管理 Maven、Gradle、Spring Boot CLI 等工具。

# 安装 SDKMAN
curl -s "https://get.sdkman.io" | bash

# 安装 JDK 17（LTS）
sdk install java 17.0.9-tem

# 切换版本
sdk use java 17.0.9-tem

# 查看已安装版本
sdk list java

SDK 开发我建议用 JDK 17 或 JDK 21。这两个都是 LTS 版本，用户覆盖面广。我曾经踩过一个坑：用 JDK 11 的 Records 特性写了个 SDK，结果用户还在用 JDK 8……那叫一个尴尬。

3.1.3 Go：Go 版本 + GVM

Go 的版本管理，GVM 是社区主流选择。不过 Go 本身向后兼容做得不错，所以如果你只维护一个项目，直接装官方包也行。

# 安装 GVM
bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)

# 安装 Go 1.21
gvm install go1.21

# 使用
gvm use go1.21

# 验证
go version

3.2 构建工具选择：Maven vs Gradle vs Go Mod

构建工具的选择，说白了就是「稳定」和「灵活」之间的权衡。我根据实际项目经验，整理了一个对比表：

我个人建议：

• Java SDK：如果团队熟悉 Maven，就用 Maven。它虽然啰嗦，但稳定。Gradle 更适合需要自定义构建逻辑的大型项目。
• Go SDK：没得选，就是 go mod。它简单到让人感动——一个 go.mod 文件搞定所有依赖。
• Python SDK：用 setuptools + pip。别折腾其他工具，社区标准就是它。

3.3 项目初始化：从零到可发布的结构

项目初始化，说白了就是搭骨架。骨架搭得好，后面写代码才舒服。我分享一下我常用的项目结构模板。

3.3.1 Python SDK 项目结构

my-sdk/
├── src/
│   └── my_sdk/
│       ├── __init__.py
│       ├── client.py
│       ├── models.py
│       └── utils.py
├── tests/
│   ├── __init__.py
│   ├── test_client.py
│   └── test_models.py
├── docs/
│   └── index.md
├── examples/
│   └── quickstart.py
├── pyproject.toml
├── setup.cfg
├── setup.py
├── README.md
├── LICENSE
└── .gitignore

初始化命令：

# 创建项目目录
mkdir my-sdk && cd my-sdk

# 初始化 pyproject.toml
cat > pyproject.toml << EOF
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-sdk"
version = "0.1.0"
description = "A sample SDK"
requires-python = ">=3.8"
EOF

# 初始化虚拟环境
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

3.3.2 Java SDK 项目结构（Maven）

my-sdk/
├── src/
│   ├── main/
│   │   └── java/
│   │       └── com/
│   │           └── example/
│   │               └── sdk/
│   │                   ├── Client.java
│   │                   ├── model/
│   │                   └── exception/
│   └── test/
│       └── java/
│           └── com/
│               └── example/
│                   └── sdk/
│                       └── ClientTest.java
├── pom.xml
├── README.md
├── LICENSE
└── .gitignore

初始化命令：

# 使用 Maven 原型生成
mvn archetype:generate \
  -DgroupId=com.example.sdk \
  -DartifactId=my-sdk \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

# 或者手动创建 pom.xml
cat > pom.xml << EOF
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example.sdk</groupId>
  <artifactId>my-sdk</artifactId>
  <version>0.1.0</version>
  <packaging>jar</packaging>
</project>
EOF

3.3.3 Go SDK 项目结构

my-sdk/
├── client.go
├── client_test.go
├── models.go
├── go.mod
├── go.sum
├── README.md
├── LICENSE
└── .gitignore

初始化命令：

# 初始化模块
mkdir my-sdk && cd my-sdk
go mod init github.com/yourname/my-sdk

# 创建主文件
cat > client.go << EOF
package mysdk

// Client is the main SDK client
type Client struct {
    APIKey string
}

// NewClient creates a new SDK client
func NewClient(apiKey string) *Client {
    return &Client{APIKey: apiKey}
}
EOF

# 添加依赖
go get github.com/google/uuid

3.4 知识体系总览

下面这张图，把本章的核心逻辑串起来了。你想想看，从语言环境到构建工具，再到项目骨架，每一步都是为后面的 SDK 开发打基础。

3.5 避坑指南

最后，分享几个我踩过的坑：

• 版本锁定要严格：在 requirements.txt 或 pom.xml 里，把依赖版本写死。别用 >= 范围，否则用户环境不同，依赖版本不同，问题就来了。
• CI 环境要模拟：本地开发环境和 CI 环境尽量一致。我建议用 Docker 来跑 CI，这样环境完全可复现。
• README 里写清楚环境要求：别让用户猜。直接写「需要 Python 3.8+，JDK 17+，Go 1.21+」。
• 别忽略 .gitignore：把 .venv/、target/、vendor/、*.pyc、.idea/ 都加进去。我曾经见过一个仓库，里面全是 IDE 配置文件……