feat: add Chapter 7 - DockerClient core objects and API reference table

docker-java-sdk-tutorial.md

@@ -1221,4 +1221,210 @@ public void opsDemo() {
 
 ***
 
-下一章，我们将总结 DockerClient 核心对象与全部 API 的对照关系，形成一份速查表。
+## DockerClient 核心对象及 API 对照表
+
+经过前面章节的学习，我们已经掌握了 Docker Java SDK 的主要使用方法。本章将对 `DockerClient` 接口的全部方法进行归类整理，形成一份**速查表**，方便日常开发时快速查找。
+
+### DockerClient 核心架构
+
+`DockerClient` 是整个 SDK 的统一入口，所有 Docker 操作都通过它来分发。它的方法返回值是各种 `*Cmd` 接口，通过链式调用设置参数后，调用 `.exec()` 真正执行。
+
+```java
+// DockerClient 方法的调用模式
+dockerClient.<命令方法>(<参数>)
+    .<参数方法>(<值>)      // 链式调用
+    .<参数方法>(<值>)
+    .exec();              // 真正执行，返回响应或回调
+```
+
+### API 全局概览
+
+以下表格列出了 `DockerClient` 接口的全部方法，按功能分类：
+
+#### 一、Docker Daemon 基本信息
+
+| 方法 | 对应命令 | 说明 |
+|------|----------|------|
+| `pingCmd()` | `docker ping` | 检测 Docker daemon 连接是否正常 |
+| `infoCmd()` | `docker info` | 获取 Docker daemon 系统信息 |
+| `versionCmd()` | `docker version` | 获取 Docker 版本信息 |
+| `authCmd()` | — | 进行 Registry 认证 |
+| `eventsCmd()` | `docker events` | 实时监听 Docker 事件 |
+
+#### 二、镜像管理
+
+| 方法 | 对应命令 | 说明 |
+|------|----------|------|
+| `listImagesCmd()` | `docker images` | 列出本地所有镜像 |
+| `inspectImageCmd(id)` | `docker inspect` (镜像) | 获取镜像完整详情 |
+| `pullImageCmd(name)` | `docker pull` | 拉取镜像（异步回调） |
+| `pushImageCmd(name)` | `docker push` | 推送镜像到 Registry |
+| `removeImageCmd(id)` | `docker rmi` | 删除本地镜像 |
+| `tagImageCmd(id, repo, tag)` | `docker tag` | 为镜像添加标签 |
+| `saveImageCmd(id)` | `docker save` | 将镜像导出为 tar 流 |
+| `saveImagesCmd()` | `docker save` (多个) | 批量导出多个镜像 |
+| `loadImageCmd(inputStream)` | `docker load` | 从 tar 流加载镜像 |
+| `searchImagesCmd(keyword)` | `docker search` | 搜索 Registry 中的镜像 |
+| `imageHistoryCmd(id)` | `docker history` | 查看镜像构建历史 |
+| `createImageCmd(name, stream)` | `docker import` | 从 tar 流创建镜像 |
+
+#### 三、镜像构建
+
+| 方法 | 对应命令 | 说明 |
+|------|----------|------|
+| `buildImageCmd()` | `docker build` | 从 Dockerfile 构建镜像 |
+| `buildImageCmd(file)` | `docker build` | 指定 Dockerfile 构建 |
+| `buildImageCmd(inputStream)` | `docker build` | 从 tar 包构建镜像 |
+
+#### 四、容器生命周期管理
+
+| 方法 | 对应命令 | 说明 |
+|------|----------|------|
+| `createContainerCmd(image)` | `docker create` | 创建容器（不启动） |
+| `startContainerCmd(id)` | `docker start` | 启动容器 |
+| `stopContainerCmd(id)` | `docker stop` | 优雅停止容器（先 SIGTERM，再 SIGKILL） |
+| `killContainerCmd(id)` | `docker kill` | 强制杀死容器（立即 SIGKILL） |
+| `restartContainerCmd(id)` | `docker restart` | 重启容器 |
+| `pauseContainerCmd(id)` | `docker pause` | 暂停容器（使用 cgroup freezer） |
+| `unpauseContainerCmd(id)` | `docker unpause` | 恢复已暂停容器 |
+| `removeContainerCmd(id)` | `docker rm` | 删除容器 |
+| `waitContainerCmd(id)` | `docker wait` | 阻塞等待容器退出（返回退出码） |
+| `renameContainerCmd(id)` | `docker rename` | 重命名容器 |
+| `updateContainerCmd(id)` | `docker update` | 更新容器运行时配置 |
+| `commitCmd(id)` | `docker commit` | 将容器状态保存为镜像 |
+| `topContainerCmd(id)` | `docker top` | 查看容器内运行的进程 |
+| `exportContainerCmd(id)` | `docker export` | 将容器文件系统导出为 tar |
+
+#### 五、容器查询
+
+| 方法 | 对应命令 | 说明 |
+|------|----------|------|
+| `listContainersCmd()` | `docker ps` | 列出容器 |
+| `inspectContainerCmd(id)` | `docker inspect` (容器) | 获取容器完整详情 |
+| `containerDiffCmd(id)` | `docker diff` | 查看容器文件系统变更 |
+| `statsCmd(id)` | `docker stats` | 获取容器资源统计 |
+
+#### 六、容器运维
+
+| 方法 | 对应命令 | 说明 |
+|------|----------|------|
+| `logContainerCmd(id)` | `docker logs` | 获取容器日志 |
+| `attachContainerCmd(id)` | `docker attach` | 连接到容器的 I/O 流 |
+| `execCreateCmd(id)` | `docker exec` (创建) | 在容器内创建命令会话 |
+| `execStartCmd(id)` | `docker exec` (启动) | 执行创建好的命令会话 |
+| `inspectExecCmd(id)` | — | 获取 exec 会话详情 |
+| `resizeExecCmd(id)` | — | 调整 exec TTY 大小 |
+| `copyArchiveFromContainerCmd(id, path)` | `docker cp` (取出) | 从容器复制文件到本地 |
+| `copyArchiveToContainerCmd(id)` | `docker cp` (放入) | 将本地文件复制到容器 |
+| `copyFileFromContainerCmd(id, path)` | `docker cp` (取出) | 从容器复制单个文件 |
+| `resizeContainerCmd(id)` | — | 调整容器 TTY 大小 |
+
+#### 七、数据卷（Volume）
+
+| 方法 | 对应命令 | 说明 |
+|------|----------|------|
+| `listVolumesCmd()` | `docker volume ls` | 列出所有数据卷 |
+| `inspectVolumeCmd(name)` | `docker volume inspect` | 查看卷详情 |
+| `createVolumeCmd()` | `docker volume create` | 创建数据卷 |
+| `removeVolumeCmd(name)` | `docker volume rm` | 删除数据卷 |
+
+#### 八、网络（Network）
+
+| 方法 | 对应命令 | 说明 |
+|------|----------|------|
+| `listNetworksCmd()` | `docker network ls` | 列出所有网络 |
+| `inspectNetworkCmd()` | `docker network inspect` | 查看网络详情 |
+| `createNetworkCmd()` | `docker network create` | 创建自定义网络 |
+| `removeNetworkCmd(id)` | `docker network rm` | 删除网络 |
+| `connectToNetworkCmd()` | `docker network connect` | 将容器接入网络 |
+| `disconnectFromNetworkCmd()` | `docker network disconnect` | 将容器移出网络 |
+
+### 核心模型类对照
+
+SDK 中的模型类与 Docker JSON API 的返回数据一一对应。以下是常用的模型类：
+
+#### Image 相关
+
+| 模型类 | 用途 | 常用字段 |
+|--------|------|----------|
+| `Image` | 镜像简要信息 | `id`, `repoTags`, `size`, `created`, `labels` |
+| `InspectImageResponse` | 镜像完整详情 | `id`, `arch`, `os`, `config`, `rootFs` |
+| `ImageHistory` | 镜像构建历史 | `created`, `createdBy`, `size` |
+
+#### Container 相关
+
+| 模型类 | 用途 | 常用字段 |
+|--------|------|----------|
+| `Container` | 容器简要信息 | `id`, `names`, `state`, `status`, `ports` |
+| `InspectContainerResponse` | 容器完整详情 | `id`, `name`, `state`, `config`, `networkSettings`, `mounts` |
+| `ContainerState` | 容器状态 | `running`, `status`, `exitCode`, `pid` |
+| `ContainerPort` | 端口映射 | `privatePort`, `publicPort`, `type` |
+| `Mount` | 挂载点 | `source`, `destination`, `mode`, `type` |
+
+#### 命令响应
+
+| 模型类 | 用途 | 常用字段 |
+|--------|------|----------|
+| `CreateContainerResponse` | 创建容器响应 | `id`, `warnings` |
+| `ExecCreateCmdResponse` | 创建 exec 响应 | `id` |
+| `Version` | 版本信息 | `version`, `apiVersion`, `buildTime` |
+| `Info` | 系统信息 | `containers`, `images`, `serverVersion` |
+
+### 回调类与异步机制
+
+Docker SDK 中的 I/O 密集操作（拉取镜像、构建镜像、执行命令等）采用异步回调模式。核心回调类：
+
+| 回调类 | 用途 | 常用方法 |
+|--------|------|----------|
+| `ResultCallback.Adapter<T>` | 通用异步回调适配器 | `onNext(T)`, `onComplete()`, `onError(Throwable)` |
+| `PullImageResultCallback` | 拉取镜像回调 | `awaitCompletion()` |
+| `BuildImageResultCallback` | 构建镜像回调 | `awaitImageId()` |
+| `WaitContainerResultCallback` | 等待容器回调 | `awaitStatusCode(timeout, unit)` |
+| `LogContainerResultCallback` | 获取日志回调 | 继承自 `ResultCallback`，逐帧回调 |
+| `ExecStartResultCallback` | 执行命令回调 | 继承自 `ResultCallback`，逐帧回调 |
+| `LoadImageResultCallback` | 加载镜像回调 | `awaitCompletion()` |
+
+### 错误处理机制
+
+SDK 中的所有 Docker 操作失败时，统一抛出 `DockerException` 的子类：
+
+| 异常类 | HTTP 状态码 | 说明 |
+|--------|-------------|------|
+| `NotFoundException` | 404 | 资源不存在（镜像/容器未找到） |
+| `ConflictException` | 409 | 资源冲突（如删除运行中的容器） |
+| `InternalServerErrorException` | 500 | Docker daemon 内部错误 |
+| `BadRequestException` | 400 | 请求参数不正确 |
+| `ForbiddenException` | 403 | 权限不足（Docker socket 权限或 Registry 认证失败） |
+
+最佳实践：在调用 Docker API 时，始终用 try-catch 捕获异常并进行适当的错误处理：
+
+```java
+try {
+    dockerClient.pingCmd().exec();
+    log.info("Docker 连接正常");
+} catch (DockerException e) {
+    // 根据异常类型进行针对性处理
+    if (e instanceof NotFoundException) {
+        log.error("请求的资源不存在");
+    } else if (e instanceof InternalServerErrorException) {
+        log.error("Docker daemon 内部错误: {}", e.getMessage());
+    } else {
+        log.error("Docker 操作失败: {}", e.getMessage());
+    }
+} catch (Exception e) {
+    log.error("网络连接失败: {}", e.getMessage());
+}
+```
+
+### 本教程代码结构
+
+| 类名 | 所在章节 | 说明 |
+|------|----------|------|
+| `QuickStart` | Chapter 2 | DockerClient 创建、连接、拉取镜像、创建启动容器 |
+| `DockerClientFactory` | Chapter 2 | DockerClient 工厂类，提供统一的实例创建方法 |
+| `ImageManageAPI` | Chapter 3 | 镜像管理（列出、查看详情、拉取、删除、标记、检查存在） |
+| `ImageBuildAPI` | Chapter 4 | 镜像构建（从 Dockerfile 构建、清理中间层） |
+| `ContainerManageAPI` | Chapter 5 | 容器管理（创建、启动、停止、删除、列出、查看详情） |
+| `ContainerOpsAPI` | Chapter 6 | 容器运维（日志、执行命令、复制文件、等待退出） |
+
+> Docker Java SDK 的 API 设计遵循"命令对象模式"：每个操作对应一个 `*Cmd` 接口，通过 Builder 模式链式设置参数，最后通过 `.exec()` 统一执行。掌握这个模式后，即使遇到本教程未覆盖的 API，也能快速上手。