📚 课程目录第3章开发环境准备

开发环境准备：JDK/Python版本选择、依赖管理工具、IDE配置

说实话，开发环境准备这一步，看起来简单，但踩过坑的人都知道——版本不对、工具不兼容、IDE配置遗漏，随便来一个就能让SDK接入卡住半天。我见过不少同事，花了一上午装环境，结果启动时报了一堆莫名其妙的依赖冲突，最后发现是JDK小版本号差了1位。所以这一章，咱们把每一步拆清楚，你跟着走基本不会出问题。

语言版本怎么选？别追新，也别太旧

我所接触的数据访问审计SDK，主流提供Java和Python两种语言的客户端库。Java版本主要依赖JDK 8或11，Python版本则要求Python 3.8以上。为什么这样选？我一个个说。

核心原则：稳定 > 新特性。SDK的生产环境接入，首要保证兼容性。JDK 8和11是LTS版本，Python 3.8也是广泛支持的稳定线。

Java：JDK 8 还是 JDK 11？

我个人习惯先用JDK 11开发，但最终部署时很多公司还在用JDK 8。SDK通常对这两个大版本做双兼容。但要注意，如果你用JDK 17或21（虽然也是LTS），有些老依赖包可能还没适配，建议先用SDK官方文档推荐的版本。举个例子，我曾经接手一个项目，团队统一用JDK 17，结果SDK里的一个序列化库在内核模块上抛了illegal reflective access警告，排查了半天才确定是版本兼容问题。

小技巧：开发机上装一个SDKMAN，快速切换多个JDK版本。我经常在JDK 11和JDK 8之间来回切，就是为了复现客户环境的问题。

Python：3.8+，但别上3.13

SDK的Python库通常基于asyncio或threading实现，要求Python 3.8及以上。但如果你用最新的3.13（没有特殊需求的话），可能会遇到某些C扩展包还没发布wheel的情况。我建议用3.10或3.11，成熟且性能好。记住，生产环境上用pyenv管理版本，比手动改PATH安全得多。

语言	推荐版本	最低版本	注意事项
Java	JDK 11	JDK 8	避免JDK 17+的反射限制
Python	3.10 / 3.11	3.8	避免3.12+的某些C扩展缺失

依赖管理工具：Maven、Gradle 与 pip

这块我有不少经验可以分享。SDK的Java版本一般同时提供Maven和Gradle两种构建系统的接入示例。Python版本则用pip + requirements.txt或pyproject.toml。你想想看，团队里有人用Maven，有人用Gradle，如果SDK只给一种，那另一组就得手动拷jar包，特别容易版本错乱。

Java：Maven 还是 Gradle？

我个人的建议是：跟着你团队的现有生态走。SDK官方文档里通常会给出两套配置代码。比如Maven的pom.xml里加dependency，Gradle的build.gradle里加implementation。这里有个坑：你复制依赖坐标时，一定要确认groupId、artifactId和版本号与SDK文档完全一致。我踩过一次，文档写的是audit-sdk:1.2.0，但实际最新版已经是1.3.0，结果用1.2.0时报了一个接口找不到的方法，折腾半小时才发现是小版本没对齐。

<!-- Maven 示例 -->
<dependency>
    <groupId>com.example</groupId>
    <artifactId>audit-sdk</artifactId>
    <version>1.3.0</version>
</dependency>

// Gradle 示例
implementation 'com.example:audit-sdk:1.3.0'

Python：pip 安装与锁定

Python这边，建议先用虚拟环境。我习惯用python -m venv .venv，然后激活。然后用pip安装SDK包：

pip install data-audit-sdk

完了之后记得执行pip freeze > requirements.txt，把整个依赖树锁住。以前我图省事没锁版本，结果同事更新了某个子依赖，SDK就崩了。嗯，现在这个习惯再没敢丢。

警告：不要把SDK安装到系统全局的Python解释器里。一旦升级了系统Python或其它包，SDK可能被覆盖或破坏。虚拟环境是必须的。

IDE配置：告别“我本地能跑，你那边不行”

IDE配置其实更偏向团队规范。我自己主力用IntelliJ IDEA，偶尔切VS Code。下面说几个关键点，能避免大多数“环境不一致”问题。

IntelliJ IDEA（Java为主）

SDK与Language Level：Project Structure里把Project SDK和Project language level分别设为JDK 11和11。我曾经见过有人Project language level设成8，但代码里用了var关键字，编译直接报错。
Maven/Gradle自动导入：打开Preferences → Build → Build Tools → Maven，勾上“Always update snapshots”和“Import Maven projects automatically”。这样pom.xml一改，依赖就自动刷新。
编码与换行符：File Encoding设成UTF-8，Line separator选Unix (\n)。这个很隐蔽，但跨Windows/Mac协作时，不同换行符会导致代码审查里全是diff。
注解处理器：有些SDK用Lombok或MapStruct，一定要在Preferences → Build → Compiler → Annotation Processors里勾选“Enable annotation processing”。我一开始没开，死活报找不到getter/setter方法。

VS Code（Python为主）

Python解释器：按Ctrl+Shift+P，输入Python: Select Interpreter，选你刚才创建的虚拟环境路径。否则终端运行时用的可能是系统Python。
安装扩展：Python、Pylance、甚至YAML（如果SDK配置是yaml格式）。我习惯把自动保存改成onFocusChange，省得每次手动保存。
代码检查：在settings.json里加上"python.linting.enabled": true和"python.linting.pylintEnabled": true。这样写代码时能顺手发现潜在问题。

强烈建议：团队统一提交.editorconfig和.gitignore，避免IDE生成的.idea或.vscode目录污染代码仓库。我有个项目就是没人管这个，结果.gitignore里没加.idea，每次合并冲突一堆。

一张图理清开发环境准备流程

下面这张图概括了从语言版本选择到IDE配置的全过程，你可以把它当作搭建环境的检查清单。

环境验证：跑通最小示例

不管用Java还是Python，我都会推荐你做的第一件事：从SDK文档里复制一个最简单的连接并审计日志的代码，直接编译运行。例如Java里：

AuditClient client = new AuditClient.Builder()
    .endpoint("https://api.example.com")
    .("your-key")
    .build();

client.logAccessEvent("user001", "file-a", "READ");
System.out.println("审计日志发送成功");

如果这一步没报错，说明SDK已经能跟服务端通信了。Python类似：

from data_audit_sdk import AuditClient
client = AuditClient(endpoint="https://api.example.com", ="your-key")
client.log_access_event("user001", "file-a", "READ")

我曾经帮一个团队排查，他们SDK里一直报java.lang.UnsatisfiedLinkError，结果是因为JDK架构不匹配——32位JDK跑了64位的JNI库。这种问题，环境验证阶段就能暴露出来，不要等到集成测试再发现。

建议：在项目的README里写清楚“最小环境要求清单”，包括JDK/Python版本、依赖管理工具版本、IDE插件列表。新成员加入时直接看这个，省去很多沟通成本。

好了，开发环境准备这块基本就这些。接下来你会看到具体的SDK依赖引入和配置初始化，那才是真正动手的地方。但环境不牢，地动山摇——这一步值得你多花十分钟检查清楚。