diff --git a/docs/zh/solar-network/developers/.nav.yml b/docs/zh/solar-network/developers/.nav.yml new file mode 100644 index 0000000..91dd459 --- /dev/null +++ b/docs/zh/solar-network/developers/.nav.yml @@ -0,0 +1,5 @@ +title: 开发者 +nav: + - index.md + - routing.md + - file-upload.md \ No newline at end of file diff --git a/docs/zh/solar-network/developers/file-upload.md b/docs/zh/solar-network/developers/file-upload.md new file mode 100644 index 0000000..7e21101 --- /dev/null +++ b/docs/zh/solar-network/developers/file-upload.md @@ -0,0 +1,102 @@ +# 文件上传 + +!!! note "本文由 DysonNetwork.Drive 提供服务" + + 在通过网关访问时,需要将 `/api` 替换成服务 ID `/drive`。 + +!!! warning "TuS 接口过时" + + 原有的 `/api/tus` 接口已经过时,即将迎来移除的命运。还请使用新的 Solar Network Multipart Upload 协议上传文件。 + +本文档概述了使用多部分上传 API 分块上传大文件的过程。 + +## 1. 创建上传任务 + +要开始文件上传,您首先需要创建一个上传任务。这是通过向 `/api/files/upload/create` 端点发送 `POST` 请求来完成的。 + +**端点:** `POST /api/files/upload/create` + +**请求体:** + +```json +{ + "hash": "string (文件哈希,例如 MD5 或 SHA256)", + "file_name": "string", + "file_size": "long (字节数)", + "content_type": "string (例如 'image/jpeg')", + "pool_id": "string (GUID,可选)", + "bundle_id": "string (GUID,可选)", + "encrypt_password": "string (可选)", + "expired_at": "string (ISO 8601 格式,可选)", + "chunk_size": "long (字节数,可选,默认 5MB)" +} +``` + +**响应:** + +如果具有相同哈希的文件已存在,服务器将返回 `200 OK`,响应体如下: + +```json +{ + "file_exists": true, + "file": { ... (CloudFile 对象,以 snake_case 格式) ... } +} +``` + +如果文件不存在,服务器将返回 `200 OK`,包含任务 ID 和分块信息: + +```json +{ + "file_exists": false, + "task_id": "string", + "chunk_size": "long", + "chunks_count": "int" +} +``` + +您将需要 `task_id`、`chunk_size` 和 `chunks_count` 用于后续步骤。 + +## 2. 上传文件分块 + +一旦您有了 `task_id`,就可以开始分块上传文件。每个分块作为带有 `multipart/form-data` 的 `POST` 请求发送。 + +**端点:** `POST /api/files/upload/chunk/{taskId}/{chunkIndex}` + +- `taskId`:上一步上传任务的 ID。 +- `chunkIndex`:您正在上传的分块的从 0 开始的索引。 + +**请求体:** + +请求体的格式应为 `multipart/form-data`,包含一个名为 `chunk` 的表单字段,其中包含该分块的二进制数据。 + +每个分块的大小应等于"创建上传任务"步骤中返回的 `chunk_size`,除了最后一个分块可能更小。 + +**响应:** + +成功的分块上传将返回 `200 OK`,响应体为空。 + +您应该上传从 `0` 到 `chunks_count - 1` 的所有分块。 + +## 3. 完成上传 + +所有分块成功上传后,您必须发送最终请求以完成上传过程。这将合并所有分块为单个文件并进行处理。 + +**端点:** `POST /api/files/upload/complete/{taskId}` + +- `taskId`:上传任务的 ID。 + +**请求体:** + +请求体应为空。 + +**响应:** + +成功的请求将返回 `200 OK`,包含新上传文件的 `CloudFile` 对象。 + +```json +{ + ... (CloudFile 对象) ... +} +``` + +如果任何分块缺失或合并过程中发生错误,服务器将返回 `400 Bad Request` 以及错误消息。 diff --git a/docs/zh/solar-network/developers/index.md b/docs/zh/solar-network/developers/index.md new file mode 100644 index 0000000..d35e77d --- /dev/null +++ b/docs/zh/solar-network/developers/index.md @@ -0,0 +1,7 @@ +# 开发者服务 + +本条目下列内容是提供给开发者阅读的,可能需要有一些技术基础才能理解。 + +在开始使用 Solar Netweork 开发之前,请确保您已充分理解并同意 [Solar Network 开发者协议](https://solsynth.dev/terms/solar-network-dev) + +本文只会提及一些需要特殊注意的地方,对于常见的 CRUD 请求请查看我们的自动生成文档 [Solar Network Swagger](https://solian.app/swagger) diff --git a/docs/zh/solar-network/developers/routing.md b/docs/zh/solar-network/developers/routing.md new file mode 100644 index 0000000..dabbd9b --- /dev/null +++ b/docs/zh/solar-network/developers/routing.md @@ -0,0 +1,44 @@ +# 路由及网关 + +众所周知,Solar Network 的服务器是一个微服务项目,所以在访问 API 的时候,您需要注意路径的指定。 + +其构造基本为 `//` + +例如,你需要访问推送服务 (DysonNetwork.Ring) 的通知 API。 + +```bash +export BASE_URL="https://api.solian.app" +export SERVICE_ID="ring" +export PATH="/notifications" +echo $BASE_URL/$SERVICE_ID$PATH +# https://api.solian.app/ring/notifications +``` + +## 服务分工 + +目前来说,Solar Network 服务端有四个各司其职的服务。 + +- Pass 负责身份验证(使用 `id` 访问) +- Ring 负责推送和通知 +- Sphere 负责聊天和帖子以及领域相关的功能 +- Develop 负责开发者相关功能 +- Drive 负责文件上传 + +其各服务的服务 ID 即为小写服务名(不包含 DysonNetwork. 前缀) + +## WebSocket + +WebSocket 由推送服务负责,但是不使用 `/ring` 服务 ID 访问,网关直接处理 `/ws` 的请求。 + +WebSocket 的消息都会使用 WebSocketPacket 结构,其结构如下: + +```json +{ + "type": "包类型", + "data": "包数据,可能为任何结构、类型", + "endpoint": "包需要请求的服务,在服务器传来的包不会携带此项;若客户端需要向服务器发送数据包,需要将此项填写为对应服务的 ID 以帮助网关转发此包", + "error_message": "服务器回传包的错误信息" +} +``` + +在访问 WebSocket 网关的时候,有两种授权方式,一种是通用的 `Authorization` 头。但是由于浏览器无法给 WebSocket 设置请求头,从而提供另一种兼容性选择,将访问令牌放置于 `?tk=` 查询参数中。