ATKONBASE

外观

SDK 总览与选型 ​

目标：在动手前选对 SDK 与通路。ATKONBASE 提供 TypeScript 与 Java 两个官方 SDK，封装两条对外通路；本页讲怎么选，逐语言用法见 TypeScript / Java。

两个 SDK、两条通路 ​

两个官方 SDK 形态对称，各自封装两条互不相干的对外通路：

通路用途入口鉴权
V1 集成 API服务端业务调用：认证 / 上传下载 / 元数据 / ACL / 版本等TypeScript AtkonbaseClient、Java AtkonbaseClientV1Auth（client token；代授权 per-call 经 actAsToken / actAsSource）
public 匿名分享终端用户匿名访问分享链接：拉元信息 / 验密码 / 下载TypeScript AtkonbasePublicClient、Java AtkonbasePublicClient无 token（验密码换 IP-bound ticket）

两条通路在类型层面彻底隔离：V1 client 编译期不可用于公开端点，public client 不接受 V1Auth，用错时编译报错。通路边界的概念背景见 API 分区。

选型：TypeScript vs Java vs 裸 HTTP ​

选项适用场景
TypeScript SDK（@atkonbase/sdk）Node ≥ 18 / 浏览器 / Worker 的 JS/TS 后端；原生支持异步 token、client.request<T>() 转义出口
Java SDK（atkonbase-sdk-java，JDK 17）Java 业务后端；独立制品，无需引入服务端模块依赖
裸 HTTP / curl其它语言栈，或只调少量端点。直接按接口参考的端点契约发请求，注意统一返回体 code 判定（见错误码参考）

两个 SDK 的能力与 IA 对称，差异主要在语言习惯（异步性、错误统一姿态、错误码常量）——详见各语言页末的「与另一 SDK 的差异」。

sdk/ 与 reference 的分工 ​

  • 本 SDK 区讲「用 SDK 怎么写」：装包、配认证、调用姿态、错误处理。
  • 接口参考（OpenAPI + Try-it）讲「端点契约」：每个端点的路径、参数、响应模型，可在线演练。

查端点字段去 reference；查「这段代码该怎么写」留在本区，两者不重复。

错误码常量 ​

ATKONBASE 的业务错误以统一返回体的 code（int）表达（见错误码参考）。两个 SDK 均提供错误码常量，同名同值、同覆盖 V1 暴露子集：

  • Java SDK：提供 ErrorCodes 常量类，覆盖 V1 客户可能命中的错误码子集，可写 e.getCode() == ErrorCodes.USER_TOKEN_INVALID。
  • TypeScript SDK：提供 errorCodes 常量集合，与 Java SDK 同名同值，可写 e.code === errorCodes.USER_TOKEN_INVALID。

也可直接按数值判定，在两个 SDK 都可用。

下一步 ​