Fanbook 开发者平台 open.fanbook.mobi 概览
开发者平台是什么
Fanbook 开发者平台的域名是 open.fanbook.mobi，它提供了：
- Bot API 文档：所有可用的 Bot API 端点、参数、响应格式
- GraphQL API：部分管理类接口采用 GraphQL 方式提供
- 应用管理后台：创建应用、添加机器人、管理 Bot Token
- API 可用类型：数据结构定义（User、Channel、Guild、Message 等）
- API 错误码：所有可能的错误响应及含义
两种 API 体系
Bot API（主要）
这是开发者最常用的接口体系，用于开发自定义 BOT。
| 特征 | 说明 |
|---|---|
| 协议 | HTTPS POST / GET |
| 地址 | https://a1.fanbook.cn/api/bot/{bot token}/{api} |
| 认证 | Bot Token（URL 路径中） |
| 用途 | 发消息、查频道、查成员、邀请管理等 |
| 文档位置 | open.fanbook.mobi/document/manage/doc/ |
GraphQL API（管理类）
用于机器人管理等后台操作。
| 特征 | 说明 |
|---|---|
| 协议 | GraphQL over HTTPS POST |
| 地址 | https://a1.fanbook.cn/api/bot/console |
| 认证 | User Token（Header 中） |
| 用途 | 更新 BOT 信息、管理 BOT 设置 |
| 文档位置 | open.fanbook.mobi/document/en/manage/doc/Bot API/机器人开发者API/ |
API 可用类型速查
这些是 API 返回的核心数据结构，类似编程语言里的「类」或「结构体」。
Channel（频道）
| Type ID | 类型名称 | 说明 |
|---|---|---|
| 0 | TextChannel | 普通文本频道 |
| 1 | VoiceChannel | 语音频道 |
| 2 | VideoChannel | 视频频道 |
| 3 | DMChannel | 私聊频道 |
| 4 | ClassChannel | 频道分类 |
| 5 | CircleChannel | 圈子 |
User（用户 / 成员）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | String | 唯一标识 |
| is_bot | Boolean | 是否是 BOT |
| username | String | 用户名 |
| first_name | String | 昵称（名） |
| last_name | String | 昵称（姓） |
| avatar | String | 头像 URL |
Chat（聊天上下文）
| 字段 | 类型 | 说明 |
|---|---|---|
| type | String | private / channel / group / supergroup |
| chat_id | String | 聊天唯一标识 |
CirclePostCoffeeInfo（圈子打赏信息）
| 字段 | 类型 | 说明 |
|---|---|---|
| give_coffee_total | Integer | 打赏的咖啡总数 |
| give_coffee_real_number | Integer | 实际打赏的总人数 |
| is_give_coffee | Integer | 当前用户是否有打赏（1 有 / 0 无） |
Permission Bits（权限位）
权限使用位运算编码，每个权限值是 2 的幂次方。见 权限设置实操。
消息体格式
Bot API 的请求体支持三种编码：
| 编码 | Content-Type | 说明 |
|---|---|---|
| JSON | application/json | 推荐，最常用 |
| 表单 | application/x-www-form-urlencoded | 简单参数场景 |
| 多部分 | multipart/form-data | 需要上传文件时（如图片） |
响应统一返回 JSON：
{
"ok": true,
"result": { ... }
}失败时：
{
"ok": false,
"error": {
"code": 400,
"message": "参数错误"
}
}开发者注册和应用创建
注册成为开发者
- 访问 open.fanbook.mobi
- 用 Fanbook 账号登录
- 同意开发者协议
创建应用
- 进入「应用管理」
- 点击「新建应用」
- 填写应用名称和描述
- 创建后，在应用详情页点击「添加机器人」
- 系统生成 Bot Token → 立即保存，它只显示一次
应用和 BOT 的关系
一个应用可以包含一个或多个机器人（取决于官方当前的限制）。每个机器人有独立的 Token 和权限。
文档版本
Fanbook 开发者文档提供中文和英文两个版本：
- 中文：open.fanbook.mobi/document/manage/doc/
- 英文：open.fanbook.mobi/document/en/manage/doc/
英文版本有时更新更快，遇到中文文档信息滞后时可以对照英文版。
开发者社区
Fanbook 是否有官方开发者社区（如 Discord 服务器、QQ 群、开发者频道）以官方最新公告为准。如果遇到 API 问题，可以：
- 查阅开发者文档的错误码章节
- 在 Fanbook 内部搜索相关 BOT 开发频道
- 联系 Fanbook 官方支持
与 Discord API 的对比
如果之前有 Discord 开发经验，会发现 Fanbook Bot API 与 Discord API 有相似之处但更精简：
| 对比项 | Discord API | Fanbook Bot API |
|---|---|---|
| 协议风格 | REST + WebSocket | REST + WebSocket |
| 认证 | Bot Token | Bot Token（类似） |
| 覆盖功能 | 非常全面 | 精简（核心场景覆盖） |
| 社区生态 | 大量第三方库和示例 | 较新，生态在发展中 |
| 文档质量 | 成熟完善 | 持续更新中 |
迁移成本： 如果做过 Discord BOT，切换到 Fanbook Bot API 的主要工作量是「熟悉新接口的参数和返回结构」，开发模式本身是通的。