# IaGenify SDK 0.2：让文件和存储资源更清晰。

Canonical URL: https://www.iagenify.com/zh/news/iagenify-sdk-02-clear-resource-objects

0.2 版明确了文件与连接存储的公共接口：应用使用稳定标识和操作，而不依赖服务内部实现细节。

## Key points
- 文件通过 `sourceId` 等稳定引用进行标识。
- 连接存储公开资源身份和实用操作，不把连接细节变成公共接口的一部分。
- SDK 资源对象描述如何使用资源，而不是服务如何实现它。

SDK 是服务与使用它的应用之间的边界。当对象描述开发者需要的操作，而不是照搬内部存储结构时，这条边界会更清晰。IaGenify SDK 0.2 为文件和连接存储明确了这一点。

## 文件是资源，而不是服务器路径

应用需要定位、读取、更新或删除文件，但不需要知道这些字节当前存放在服务机器的哪个目录。文件对象因此围绕来源标识和支持的操作设计。


```
const file = await api.files.get(sourceId);
console.log(file.sourceId);
file.content = "Revised note";
await file.update();
```

稳定标识让应用代码更具可移植性。同一个引用可以用于本地工具、网页界面或自动化，而无需了解服务器文件系统。

## 连接存储公开有用的操作

连接存储资源应让应用能够使用该连接。公共对象提供资源身份和可用操作；应用无需检查凭据即可列出或使用存储。


```
const storage = await api.storage.get({ id: storageId });
console.log(storage.id);
const files = await storage.run({ action: "list", path: "/reports" });
```

这样职责更明确：应用选择操作，服务使用已保存的连接来执行。调用方无需把连接信息复制进自己的状态。

## 更聚焦的公共接口更容易维护

如果 SDK 返回内部实现细节，应用可能会依赖这些本来不属于稳定契约的信息。之后移除它们就会造成破坏。更聚焦的对象更容易文档化，也更容易跨运行环境演进。

这不是隐藏有用功能，而是在合适层级公开它们：用标识指向资源，用方法执行支持的操作，并返回应用可以处理的结果。

## 0.2 版背后的原则

IaGenify SDK 0.2 虽然是小版本，却体现了一个重要原则：公共对象提供应用所需的信息，而不要求应用了解服务内部细节。

> 可靠的 SDK 提供稳定引用和清晰操作，同时由服务掌控内部实现。

## FAQ
### 为什么用文件标识而不是路径？
标识在不同运行环境和存储变化中仍然有效；路径只描述某一种实现。

### 应用需要连接存储的凭据吗？
服务会使用已配置的连接。应用调用支持的操作即可，无需复制凭据。

### SDK 0.2 会修改文件内容吗？
不会。它明确的是公共资源对象以及应用访问资源时使用的引用。

### 总体设计原则是什么？
让 SDK 契约聚焦于可识别的资源和受支持的操作。