docs: add comprehensive client API reference

2026-08-11 19:09:29 +08:00
parent 5b5f6f8f00
commit 2d1deb54f0
27 changed files with 10727 additions and 4 deletions
--- a/wiki/api/15-relation.md
+++ b/wiki/api/15-relation.md
@@ -0,0 +1,599 @@
+# RELATION API
+
+关注、好友和关系匹配。
+
+> 本文档由 protobuf descriptor 生成。字段名采用 protobuf JSON 名称；64 位整数在 JSON 中应按字符串处理。
+
+## 接入方式
+
+- 动态 HTTP：`POST /rpc/relation/{Service}/{Method}`
+- 原生 gRPC：`/relation.{Service}/{Method}`
+- grpc-gateway：`POST /relation.{Service}/{Method}`
+- 鉴权：需要登录的接口通过 `Authorization: Bearer <token>` 传递凭证。
+- 动态 HTTP 成功或失败均返回 HTTP 200，业务状态见 `code`、`message`、`details`。
+
+## 服务概览
+
+| 服务 | 方法数 | 说明 |
+|---|---:|---|
+| `Follow` | 4 | Follow 服务 |
+| `Friend` | 17 | Friend 服务 |
+| `Match` | 4 | Match 服务 |
+
+## Follow
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Doing` | `POST /rpc/relation/Follow/Doing` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `Undo` | `POST /rpc/relation/Follow/Undo` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `State` | `POST /rpc/relation/Follow/State` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `Fetch` | `POST /rpc/relation/Follow/Fetch` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`blocks.FetchRelationItemReply`](#blocksfetchrelationitemreply) | Unary |
+
+### Follow.Doing
+
+- 动态 HTTP：`POST /rpc/relation/Follow/Doing`
+- gRPC：`/relation.Follow/Doing`
+- 白名单键：`relation.Follow.Doing`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Follow.Undo
+
+- 动态 HTTP：`POST /rpc/relation/Follow/Undo`
+- gRPC：`/relation.Follow/Undo`
+- 白名单键：`relation.Follow.Undo`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Follow.State
+
+- 动态 HTTP：`POST /rpc/relation/Follow/State`
+- gRPC：`/relation.Follow/State`
+- 白名单键：`relation.Follow.State`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Follow.Fetch
+
+- 动态 HTTP：`POST /rpc/relation/Follow/Fetch`
+- gRPC：`/relation.Follow/Fetch`
+- 白名单键：`relation.Follow.Fetch`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+## Friend
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Search` | `POST /rpc/relation/Friend/Search` | [`blocks.SearchRequest`](#blockssearchrequest) | [`relation.PartFriendReply`](#relationpartfriendreply) | Unary |
+| `Fetch` | `POST /rpc/relation/Friend/Fetch` | [`blocks.VersionRequest`](#blocksversionrequest) | [`relation.FriendsReply`](#relationfriendsreply) | Unary |
+| `Get` | `POST /rpc/relation/Friend/Get` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.RelationItem`](#blocksrelationitem) | Unary |
+| `ModifyNickname` | `POST /rpc/relation/Friend/ModifyNickname` | [`relation.ModifyNicknameRequest`](#relationmodifynicknamerequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `DoPopular` | `POST /rpc/relation/Friend/DoPopular` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `UndoPopular` | `POST /rpc/relation/Friend/UndoPopular` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `Delete` | `POST /rpc/relation/Friend/Delete` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `ApplyFetch` | `POST /rpc/relation/Friend/ApplyFetch` | [`blocks.VersionRequest`](#blocksversionrequest) | [`relation.ApplyFetchReply`](#relationapplyfetchreply) | Unary |
+| `ApplyGet` | `POST /rpc/relation/Friend/ApplyGet` | [`blocks.IdentRequest`](#blocksidentrequest) | [`relation.FriendApplyGetReply`](#relationfriendapplygetreply) | Unary |
+| `ApplyDo` | `POST /rpc/relation/Friend/ApplyDo` | [`relation.ApplyDoRequest`](#relationapplydorequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `ApplyDoMessage` | `POST /rpc/relation/Friend/ApplyDoMessage` | [`relation.ApplyMessageRequest`](#relationapplymessagerequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `ApplyDoPass` | `POST /rpc/relation/Friend/ApplyDoPass` | [`relation.ApplyDoPassRequest`](#relationapplydopassrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `ApplyDoReject` | `POST /rpc/relation/Friend/ApplyDoReject` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `TagFetch` | `POST /rpc/relation/Friend/TagFetch` | [`blocks.Empty`](#blocksempty) | [`relation.FriendTagsReply`](#relationfriendtagsreply) | Unary |
+| `TagMemberFetch` | `POST /rpc/relation/Friend/TagMemberFetch` | [`blocks.IdentRequest`](#blocksidentrequest) | [`relation.PartFriendReply`](#relationpartfriendreply) | Unary |
+| `TagDoCreate` | `POST /rpc/relation/Friend/TagDoCreate` | [`relation.TagDoCreateRequest`](#relationtagdocreaterequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `TagDoUpdate` | `POST /rpc/relation/Friend/TagDoUpdate` | [`relation.TagDoUpdateRequest`](#relationtagdoupdaterequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+
+### Friend.Search
+
+- 动态 HTTP：`POST /rpc/relation/Friend/Search`
+- gRPC：`/relation.Friend/Search`
+- 白名单键：`relation.Friend.Search`
+- 请求示例：
+
+```json
+{
+  "keyword": "string"
+}
+```
+
+### Friend.Fetch
+
+- 动态 HTTP：`POST /rpc/relation/Friend/Fetch`
+- gRPC：`/relation.Friend/Fetch`
+- 白名单键：`relation.Friend.Fetch`
+- 请求示例：
+
+```json
+{
+  "version": "0"
+}
+```
+
+### Friend.Get
+
+- 动态 HTTP：`POST /rpc/relation/Friend/Get`
+- gRPC：`/relation.Friend/Get`
+- 白名单键：`relation.Friend.Get`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.ModifyNickname
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ModifyNickname`
+- gRPC：`/relation.Friend/ModifyNickname`
+- 白名单键：`relation.Friend.ModifyNickname`
+- 请求示例：
+
+```json
+{
+  "identity": "string",
+  "nickname": "string"
+}
+```
+
+### Friend.DoPopular
+
+- 动态 HTTP：`POST /rpc/relation/Friend/DoPopular`
+- gRPC：`/relation.Friend/DoPopular`
+- 白名单键：`relation.Friend.DoPopular`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.UndoPopular
+
+- 动态 HTTP：`POST /rpc/relation/Friend/UndoPopular`
+- gRPC：`/relation.Friend/UndoPopular`
+- 白名单键：`relation.Friend.UndoPopular`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.Delete
+
+- 动态 HTTP：`POST /rpc/relation/Friend/Delete`
+- gRPC：`/relation.Friend/Delete`
+- 白名单键：`relation.Friend.Delete`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.ApplyFetch
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyFetch`
+- gRPC：`/relation.Friend/ApplyFetch`
+- 白名单键：`relation.Friend.ApplyFetch`
+- 请求示例：
+
+```json
+{
+  "version": "0"
+}
+```
+
+### Friend.ApplyGet
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyGet`
+- gRPC：`/relation.Friend/ApplyGet`
+- 白名单键：`relation.Friend.ApplyGet`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.ApplyDo
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyDo`
+- gRPC：`/relation.Friend/ApplyDo`
+- 白名单键：`relation.Friend.ApplyDo`
+- 请求示例：
+
+```json
+{
+  "body": "string",
+  "toId": "0",
+  "toIdentity": "string"
+}
+```
+
+### Friend.ApplyDoMessage
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyDoMessage`
+- gRPC：`/relation.Friend/ApplyDoMessage`
+- 白名单键：`relation.Friend.ApplyDoMessage`
+- 请求示例：
+
+```json
+{
+  "applyId": "0",
+  "body": "string"
+}
+```
+
+### Friend.ApplyDoPass
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyDoPass`
+- gRPC：`/relation.Friend/ApplyDoPass`
+- 白名单键：`relation.Friend.ApplyDoPass`
+- 请求示例：
+
+```json
+{
+  "applyIdentity": "string",
+  "friendRelationId": "0",
+  "friendRelationIdentity": "string"
+}
+```
+
+### Friend.ApplyDoReject
+
+- 动态 HTTP：`POST /rpc/relation/Friend/ApplyDoReject`
+- gRPC：`/relation.Friend/ApplyDoReject`
+- 白名单键：`relation.Friend.ApplyDoReject`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.TagFetch
+
+- 动态 HTTP：`POST /rpc/relation/Friend/TagFetch`
+- gRPC：`/relation.Friend/TagFetch`
+- 白名单键：`relation.Friend.TagFetch`
+- 请求示例：
+
+```json
+{}
+```
+
+### Friend.TagMemberFetch
+
+- 动态 HTTP：`POST /rpc/relation/Friend/TagMemberFetch`
+- gRPC：`/relation.Friend/TagMemberFetch`
+- 白名单键：`relation.Friend.TagMemberFetch`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Friend.TagDoCreate
+
+- 动态 HTTP：`POST /rpc/relation/Friend/TagDoCreate`
+- gRPC：`/relation.Friend/TagDoCreate`
+- 白名单键：`relation.Friend.TagDoCreate`
+- 请求示例：
+
+```json
+{
+  "friendIdentity": [
+    "string"
+  ],
+  "tagName": "string"
+}
+```
+
+### Friend.TagDoUpdate
+
+- 动态 HTTP：`POST /rpc/relation/Friend/TagDoUpdate`
+- gRPC：`/relation.Friend/TagDoUpdate`
+- 白名单键：`relation.Friend.TagDoUpdate`
+- 请求示例：
+
+```json
+{
+  "direction": "string",
+  "friendIdentity": "string",
+  "tagIdentity": "string"
+}
+```
+
+## Match
+
+| 方法 | 动态 HTTP 路径 | 请求 | 响应 | 类型 |
+|---|---|---|---|---|
+| `Fetch` | `POST /rpc/relation/Match/Fetch` | [`blocks.FetchRequest`](#blocksfetchrequest) | [`blocks.FetchRelationItemReply`](#blocksfetchrelationitemreply) | Unary |
+| `Get` | `POST /rpc/relation/Match/Get` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.RelationItem`](#blocksrelationitem) | Unary |
+| `DoJoin` | `POST /rpc/relation/Match/DoJoin` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+| `DoIgnore` | `POST /rpc/relation/Match/DoIgnore` | [`blocks.IdentRequest`](#blocksidentrequest) | [`blocks.DataStatusReply`](#blocksdatastatusreply) | Unary |
+
+### Match.Fetch
+
+- 动态 HTTP：`POST /rpc/relation/Match/Fetch`
+- gRPC：`/relation.Match/Fetch`
+- 白名单键：`relation.Match.Fetch`
+- 请求示例：
+
+```json
+{
+  "page_no": "0",
+  "page_size": "0",
+  "params": {
+    "key": "string"
+  }
+}
+```
+
+### Match.Get
+
+- 动态 HTTP：`POST /rpc/relation/Match/Get`
+- gRPC：`/relation.Match/Get`
+- 白名单键：`relation.Match.Get`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Match.DoJoin
+
+- 动态 HTTP：`POST /rpc/relation/Match/DoJoin`
+- gRPC：`/relation.Match/DoJoin`
+- 白名单键：`relation.Match.DoJoin`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+### Match.DoIgnore
+
+- 动态 HTTP：`POST /rpc/relation/Match/DoIgnore`
+- gRPC：`/relation.Match/DoIgnore`
+- 白名单键：`relation.Match.DoIgnore`
+- 请求示例：
+
+```json
+{
+  "id": "0",
+  "identity": "string"
+}
+```
+
+## 消息结构
+
+### blocks.DataStatusReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `string` | 可选 |
+| `timeseq` | `int64` | 可选 |
+
+### blocks.Empty
+
+空消息：请求时发送 `{}`。
+
+### blocks.FetchRelationItemReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int64` | 可选 |
+| `data` | `[]blocks.RelationItem` | 数组 |
+
+### blocks.FetchRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `page_no` | `int64` | 可选 |
+| `page_size` | `int64` | 可选 |
+| `params` | `map<string, string>` | 对象映射 |
+
+### blocks.FetchRequest.ParamsEntry
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `key` | `string` | 可选 |
+| `value` | `string` | 可选 |
+
+### blocks.IdentRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+
+### blocks.RelationItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `nickname` | `string` | 可选 |
+| `remarkName` | `string` | 可选 |
+| `popular` | `int32` | 可选 |
+| `avatar` | `string` | 可选 |
+| `birthday` | `string` | 可选 |
+| `sex` | `int32` | 可选 |
+| `province` | `int32` | 可选 |
+| `city` | `int32` | 可选 |
+| `area` | `int32` | 可选 |
+| `sign` | `string` | 可选 |
+| `tags` | `[]string` | 数组 |
+| `foreignStatus` | `int32` | 可选 |
+
+### blocks.SearchRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `keyword` | `string` | 可选 |
+
+### blocks.VersionRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `version` | `int64` | 可选 |
+
+### relation.ApplyDoPassRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `friendRelationId` | `int64` | 可选 |
+| `friendRelationIdentity` | `string` | 可选 |
+| `applyIdentity` | `string` | 可选 |
+
+### relation.ApplyDoRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `toId` | `int64` | 可选 |
+| `toIdentity` | `string` | 可选 |
+| `body` | `string` | 可选 |
+
+### relation.ApplyFetchReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int32` | 可选 |
+| `version` | `int64` | 可选 |
+| `applys` | `[]relation.ApplyItem` | 数组 |
+
+### relation.ApplyItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `from` | `blocks.RelationItem` | 可选 |
+| `message` | `relation.MessageItem` | 可选 |
+| `createdAt` | `string` | 可选 |
+| `status` | `int32` | 可选 |
+
+### relation.ApplyMessageRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `applyId` | `int64` | 可选 |
+| `body` | `string` | 可选 |
+
+### relation.FriendApplyGetReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `data` | `blocks.RelationItem` | 可选 |
+| `message` | `[]relation.MessageItem` | 数组 |
+
+### relation.FriendTagsReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int64` | 可选 |
+| `data` | `[]relation.TagItem` | 数组 |
+
+### relation.FriendsReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int32` | 可选 |
+| `version` | `int64` | 可选 |
+| `tags` | `[]relation.TagItem` | 数组 |
+| `friends` | `[]blocks.RelationItem` | 数组 |
+
+### relation.MessageItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `relationIdentity` | `string` | 可选 |
+| `body` | `string` | 可选 |
+| `createdAt` | `string` | 可选 |
+
+### relation.ModifyNicknameRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `identity` | `string` | 可选 |
+| `nickname` | `string` | 可选 |
+
+### relation.PartFriendReply
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `total` | `int32` | 可选 |
+| `version` | `int64` | 可选 |
+| `friends` | `[]blocks.RelationItem` | 数组 |
+
+### relation.TagDoCreateRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `tagName` | `string` | 可选 |
+| `friendIdentity` | `[]string` | 数组 |
+
+### relation.TagDoUpdateRequest
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `tagIdentity` | `string` | 可选 |
+| `friendIdentity` | `string` | 可选 |
+| `direction` | `string` | 可选 |
+
+### relation.TagItem
+
+| JSON 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | `int64` | 可选 |
+| `identity` | `string` | 可选 |
+| `friendTotal` | `int64` | 可选 |
+| `tagName` | `string` | 可选 |