MDClub JavaScript SDK 文档

MDClub 是一个 Material Design 风格的社区应用。

接口文档说明

  • 接口描述中,若含 🔑 图标,表示该接口需要登录后才能调用。
  • 接口描述中,若含 🔐 图标,表示该接口需要登录、且仅管理员有权限调用。
  • 接口返回值的字段描述中,若含 🔐 图标,表示只有管理员调用接口时,返回值中才会包含该字段。
  • 接口参数的描述中,若含 🔐 图标,表示只有管理员才能添加该参数。

GETPUTDELETE 请求均符合幂等性。

SDK 完全使用 TypeScript 开发,建议使用 Visual Studio Code、WebStorm 这类对 TypeScript 支持较好的编辑器,可以获得非常好的代码类型提示。

注意:请不要在官方的体验社区进行 API 测试,否则将直接封号。

使用详解

通过 CDN 引入 JS 文件使用

CDN 的方式仅适用于浏览器环境。

在 HTML 中通过 <script> 标签引入 JS 文件:

<script
  src="https://unpkg.com/mdclub-sdk-js@1.0.4/dist/mdclub-sdk.min.js"
  integrity="sha256-h4XtKOU7LD8xH509/AbdZxu/4LiRvtxAUaRFCjj6xOk="
  crossorigin="anonymous"
></script>

然后就可以通过全局变量 mdclubSDK 访问 SDK 了。

你可以先通过 mdclubSDK.defaults 对 SDK 进行一些设置:

// 设置 api 地址(可选,默认为 {当前域名}/api)
mdclubSDK.defaults.apiPath = 'https://example.com/api';

// 若浏览器不支持 patch, put, delete 请求,则需要将该选项设为 true
mdclubSDK.defaults.methodOverride = true;

// 设置全局回调函数(可选)
mdclubSDK.defaults.beforeSend = function () {};
mdclubSDK.defaults.success = function (response) {};
mdclubSDK.defaults.error = function (errMsg) {};
mdclubSDK.defaults.complete = function () {};

然后可以如下调用 SDK 中的方法:

mdclubSDK.QuestionApi.getList({ question_id: 11 })
  .then((questions) => {
    console.log(questions);
  })
  .catch((errMsg) => {
    console.log(errMsg);
  });

在 ES6 模块化环境或小程序中使用

使用 npm 安装 SDK:

npm install mdclub-sdk-js --save

SDK 同时支持浏览器环境和小程序环境,你需要先根据使用环境设置适配器。

若在小程序中使用,需要设置成小程序适配器。支持微信小程序、支付宝小程序、钉钉小程序、百度小程序(注意:当前代码还未在小程序中进行过测试):

import defaults from 'mdclub-sdk-js/es/defaults';
import MiniProgramAdapter from 'mdclub-sdk-js/es/adapter/MiniProgramAdapter';

defaults.adapter = new MiniProgramAdapter();

若在浏览器中使用,设置成浏览器适配器:

import defaults from 'mdclub-sdk-js/es/defaults';
import BrowserAdapter from 'mdclub-sdk-js/es/adapter/BrowserAdapter';

defaults.adapter = new BrowserAdapter();

若你的项目中已经通过 npm 安装了 jQuery、axios 之类的库,则可以设置对应的适配器,SDK 将直接使用对应的库提供的 ajax 方法。下面是所有支持的适配器:

适配器使用方法说明
AxiosAdapter
import defaults from 'mdclub-sdk-js/es/defaults';
import AxiosAdapter from 'mdclub-sdk-js/es/adapter/AxiosAdapter';

defaults.adapter = new AxiosAdapter();
使用 axios 发送请求
BrowserAdapter
import defaults from 'mdclub-sdk-js/es/defaults';
import BrowserAdapter from 'mdclub-sdk-js/es/adapter/BrowserAdapter';

defaults.adapter = new BrowserAdapter();
使用 mdui.jq 发送请求
FetchAdapter
import defaults from 'mdclub-sdk-js/es/defaults';
import FetchAdapter from 'mdclub-sdk-js/es/adapter/FetchAdapter';

defaults.adapter = new FetchAdapter();
使用浏览器内置的 fetch 方法发送请求
JQueryAdapter
import defaults from 'mdclub-sdk-js/es/defaults';
import JQueryAdapter from 'mdclub-sdk-js/es/adapter/JQueryAdapter';

defaults.adapter = new JQueryAdapter();
使用 jQuery 发送请求
MiniProgramAdapter
import defaults from 'mdclub-sdk-js/es/defaults';
import MiniProgramAdapter from 'mdclub-sdk-js/es/adapter/MiniProgramAdapter';

defaults.adapter = new MiniProgramAdapter();
在小程序内使用

还可以选择对 SDK 进行一些全局设置,这些设置都是可选的。

import defaults from 'mdclub-sdk-js/es/defaults';

// 设置 api 地址,默认为 {当前域名}/api
defaults.apiPath = 'https://example.com/api';

// 若浏览器不支持 patch, put, delete 方法,则需要将该选项设为 true
defaults.methodOverride = true;

// 设置全局回调函数
defaults.beforeSend = () => {};
defaults.success = () => {};
defaults.error = () => {};
defaults.complete = () => {};

然后就可以调用 SDK 方法了:

import QuestionApi from 'mdclub-sdk-js/es/QuestionApi';

QuestionApi.getList({ question_id: 11 })
  .then((questions) => {
    console.log(questions);
  })
  .catch((errMsg) => {
    console.log(errMsg);
  });

参数与返回值

所有 SDK 方法,都只有一个参数,参数类型为对象。

所有方法的返回值都是 Promise。若请求成功,即响应的 code 为 0,则 Promise 的状态为 reslove;若响应的 code 大于 0,则 Promise 的状态为 reject。

下面的例子是调用 QuestionApi.getList 方法的示例:

// 导入 QuestionApi 分组下的所有方法
import QuestionApi from 'mdclub-sdk-js/es/QuestionApi';

// 调用方法,参数为一个对象
QuestionApi.getList({ question_id: 11 })
  .then((questions) => {
    // 响应的 code 为 0
    console.log(questions);
  })
  .catch((err) => {
    // 响应的 code 大于 0,错误代码所表示的含义见下面的“错误代码”部分
    console.log(err);
  });

用户登录

用户登录功能需调用 TokenApi.login 方法,在该方法调用成功后,SDK 会自动保存登录 token,在通过 SDK 调用其他方法时,会自动携带上 token。

因此,使用 SDK 时,你无需考虑如何保存登录状态。

错误代码

错误代码常量名错误说明
100000SYSTEM_ERROR服务器错误
100001SYSTEM_MAINTAIN系统维护中
100002SYSTEM_IP_LIMITIP 请求超过上限
100003SYSTEM_USER_LIMIT用户请求超过上限
100004SYSTEM_API_NOT_FOUND接口不存在
100005SYSTEM_API_NOT_ALLOWED该接口不支持此 HTTP METHOD
100006SYSTEM_REQUEST_JSON_INVALID请求参数的 json 格式错误
100007SYSTEM_INSTALL_FAILED系统安装失败
200001COMMON_FIELD_VERIFY_FAILED字段验证失败
200002COMMON_SEND_EMAIL_FAILED邮件发送失败
200003COMMON_EMAIL_VERIFY_EXPIRED邮件验证码已失效
200004COMMON_IMAGE_UPLOAD_FAILED图片上传失败
200005COMMON_IMAGE_NOT_FOUND指定图片不存在
200006COMMON_VOTE_TYPE_ERROR投票类型只能是 up、down 中的一个
201001USER_NEED_LOGIN用户未登录
201002USER_NEED_MANAGE_PERMISSION需要管理员权限
201003USER_NOT_FOUND指定用户不存在
201004USER_TARGET_NOT_FOUND目标用户不存在
201005USER_DISABLED该用户已被禁用
201006USER_PASSWORD_ERROR账号或密码错误
201007USER_AVATAR_UPLOAD_FAILED头像上传失败
201008USER_COVER_UPLOAD_FAILED封面上传失败
201009USER_CANT_FOLLOW_YOURSELF不能关注你自己
202001QUESTION_NOT_FOUND指定提问不存在
202002QUESTION_CANT_EDIT提问发表后即无法编辑
202003QUESTION_CANT_EDIT_NOT_AUTHOR仅提问作者可以编辑提问
202004QUESTION_CANT_EDIT_TIMEOUT已超过可编辑的时间
202005QUESTION_CANT_EDIT_HAS_ANSWER该提问下已有回答,不允许编辑
202006QUESTION_CANT_EDIT_HAS_COMMENT该提问下已有评论,不允许编辑
202007QUESTION_CANT_DELETE提问发表后即无法删除
202008QUESTION_CANT_DELETE_NOT_AUTHOR仅提问作者可以删除提问
202009QUESTION_CANT_DELETE_TIMEOUT已超过可删除的时间
202010QUESTION_CANT_DELETE_HAS_ANSWER该提问下已有回答,不允许删除
202011QUESTION_CANT_DELETE_HAS_COMMENT该提问下已有评论,不允许删除
203001ANSWER_NOT_FOUND指定回答不存在
203002ANSWER_CANT_EDIT回答发表后即无法编辑
203003ANSWER_CANT_EDIT_NOT_AUTHOR仅回答的作者可以编辑回答
203004ANSWER_CANT_EDIT_TIMEOUT已超过可编辑的时间
203005ANSWER_CANT_EDIT_HAS_COMMENT该回答下已有评论,不允许编辑
203006ANSWER_CANT_DELETE回答发表后即无法删除
203007ANSWER_CANT_DELETE_NOT_AUTHOR仅回答的作者可以删除回答
203008ANSWER_CANT_DELETE_TIMEOUT已超过可删除的时间
203009ANSWER_CANT_DELETE_HAS_COMMENT该回答下已有评论,不允许删除
204001COMMENT_NOT_FOUND指定的评论不存在
204002COMMENT_CANT_EDIT评论发表后即无法编辑
204003COMMENT_CANT_EDIT_NOT_AUTHOR仅评论的作者可以编辑评论
204004COMMENT_CANT_EDIT_TIMEOUT已超过可编辑时间
204005COMMENT_CANT_DELETE评论发表后即无法删除
204006COMMENT_CANT_DELETE_NOT_AUTHOR仅评论的作者可以删除评论
204007COMMENT_CANT_DELETE_TIMEOUT已超过可删除时间
205001TOPIC_NOT_FOUND指定话题不存在
205002TOPIC_COVER_UPLOAD_FAILED话题封面上传失败
206001ARTICLE_NOT_FOUND指定文章不存在
206002ARTICLE_CANT_EDIT_NOT_AUTHOR文章发表后即无法编辑
206003ARTICLE_CANT_EDIT仅文章作者可以编辑文章
206004ARTICLE_CANT_EDIT_TIMEOUT已超过可编辑时间
206005ARTICLE_CANT_EDIT_HAS_COMMENT该文章下已有评论,不允许编辑
206006ARTICLE_CANT_DELETE_NOT_AUTHOR文章发表后即无法删除
206007ARTICLE_CANT_DELETE仅文章作者可以删除文章
206008ARTICLE_CANT_DELETE_TIMEOUT已超过可删除时间
206009ARTICLE_CANT_DELETE_HAS_COMMENT该文章下已有评论,不允许删除
207001REPORT_NOT_FOUND指定举报不存在
207002REPORT_TARGET_NOT_FOUND举报目标不存在
207003REPORT_ALREADY_SUBMITTED不能重复举报
208001NOTIFICATION_NOT_FOUND指定通知不存在

方法列表

身份验证

方法名描述
TokenApi.login生成 Token

系统设置

方法名描述
OptionApi.get获取站点全局设置参数
OptionApi.update🔐更新站点全局设置

用户

方法名描述
UserApi.getMyAnswers🔑获取当前登录用户发表的回答
UserApi.getMyArticles🔑获取当前登录用户发表的文章
UserApi.uploadMyAvatar🔑上传当前登录用户的头像
UserApi.deleteMyAvatar🔑删除当前登录用户的头像,并重置为默认头像
UserApi.getMyComments🔑获取当前登录用户发表的评论
UserApi.uploadMyCover🔑上传当前登录用户的封面
UserApi.deleteMyCover🔑删除当前登录用户的封面,并重置为默认封面
UserApi.getMyFollowees🔑获取当前登录用户关注的用户
UserApi.getMyFollowers🔑获取当前登录用户的关注者
UserApi.getMyFollowingArticles🔑获取登录用户关注的文章
UserApi.getMyFollowingQuestions🔑获取登录用户关注的提问
UserApi.getMyFollowingTopics🔑获取登录用户关注的话题
UserApi.sendPasswordResetEmail发送重置密码邮箱验证码
UserApi.updatePassword验证邮箱并更新密码
UserApi.getMyQuestions🔑获取登录用户发表的提问
UserApi.sendRegisterEmail发送注册邮箱验证码
UserApi.getMine🔑获取当前登录用户的信息
UserApi.updateMine🔑更新当前登录用户信息
UserApi.getList获取用户列表
UserApi.register验证邮箱并创建账号
UserApi.disableMultiple🔐批量禁用用户
UserApi.enableMultiple🔐批量恢复用户
UserApi.getAnswers获取指定用户发表的回答
UserApi.getArticles获取指定用户发表的文章
UserApi.deleteAvatar🔐删除指定用户的头像,并重置为默认头像
UserApi.getComments获取指定用户发表的评论
UserApi.deleteCover🔐删除指定用户的封面,并重置为默认封面
UserApi.disable🔐禁用指定用户
UserApi.enable🔐恢复指定用户
UserApi.getFollowees获取指定用户关注的用户列表
UserApi.getFollowers获取指定用户的关注者
UserApi.addFollow🔑添加关注
UserApi.deleteFollow🔑取消关注
UserApi.getFollowingArticles获取指定用户关注的文章列表
UserApi.getFollowingQuestions获取指定用户关注的提问列表
UserApi.getFollowingTopics获取指定用户关注的话题列表
UserApi.getQuestions获取指定用户发表的提问
UserApi.get获取指定用户信息
UserApi.update🔐更新指定用户信息

话题

方法名描述
TopicApi.getList获取全部话题
TopicApi.create🔐发布话题
TopicApi.trashMultiple🔐批量把话题放入回收站
TopicApi.untrashMultiple🔐批量把话题移出回收站
TopicApi.deleteMultiple🔐批量删除话题
TopicApi.getArticles获取指定话题下的文章
TopicApi.getFollowers获取指定话题的关注者
TopicApi.addFollow🔑关注指定话题
TopicApi.deleteFollow🔑取消关注指定话题
TopicApi.getQuestions获取指定话题下的提问
TopicApi.trash🔐把话题放入回收站
TopicApi.untrash🔐把话题移出回收站
TopicApi.get获取指定话题信息
TopicApi.update🔐更新话题信息
TopicApi.del🔐删除话题

提问

方法名描述
QuestionApi.getList获取提问列表
QuestionApi.create🔑发表提问
QuestionApi.trashMultiple🔐批量把提问放入回收站
QuestionApi.untrashMultiple🔐批量把提问移出回收站
QuestionApi.deleteMultiple🔐批量删除提问
QuestionApi.getAnswers获取指定提问下的回答
QuestionApi.createAnswer🔑在指定提问下发表回答
QuestionApi.getComments获取指定提问的评论
QuestionApi.createComment🔑在指定提问下发表评论
QuestionApi.getFollowers获取指定提问的关注者
QuestionApi.addFollow🔑添加关注
QuestionApi.deleteFollow🔑取消关注
QuestionApi.trash🔐把提问放入回收站
QuestionApi.untrash🔐把提问移出回收站
QuestionApi.getVoters获取提问的投票者
QuestionApi.addVote🔑为提问投票
QuestionApi.deleteVote🔑取消为提问的投票
QuestionApi.get获取指定提问信息
QuestionApi.update🔑更新提问信息
QuestionApi.del🔑删除提问

回答

方法名描述
AnswerApi.getList🔐获取回答列表
AnswerApi.trashMultiple🔐批量把回答放入回收站
AnswerApi.untrashMultiple🔐批量把回答移出回收站
AnswerApi.deleteMultiple🔐批量删除回答
AnswerApi.getComments获取指定回答的评论
AnswerApi.createComment在指定回答下发表评论
AnswerApi.trash🔐把回答放入回收站
AnswerApi.untrash🔐把回答移出回收站
AnswerApi.getVoters获取回答的投票者
AnswerApi.addVote🔑为回答投票
AnswerApi.deleteVote🔑取消为回答的投票
AnswerApi.get获取回答详情
AnswerApi.update🔑修改回答信息
AnswerApi.del🔑删除回答

文章

方法名描述
ArticleApi.getList获取文章列表
ArticleApi.create🔑发表文章
ArticleApi.trashMultiple🔐批量把文章放入回收站
ArticleApi.untrashMultiple🔐批量把文章移出回收站
ArticleApi.deleteMultiple🔐批量删除文章
ArticleApi.getComments获取指定文章的评论列表
ArticleApi.createComment🔑在指定文章下发表评论
ArticleApi.getFollowers获取指定文章的关注者
ArticleApi.addFollow🔑添加关注
ArticleApi.deleteFollow🔑取消关注
ArticleApi.trash🔐把文章放入回收站
ArticleApi.untrash🔐把文章移出回收站
ArticleApi.getVoters获取文章的投票者
ArticleApi.addVote🔑为文章投票
ArticleApi.deleteVote🔑取消为文章的投票
ArticleApi.get获取指定文章信息
ArticleApi.update🔑更新文章信息
ArticleApi.del🔑删除文章

评论

方法名描述
CommentApi.getList🔐获取所有评论
CommentApi.trashMultiple🔐批量把评论放入回收站
CommentApi.untrashMultiple🔐批量把评论移出回收站
CommentApi.deleteMultiple🔐批量删除评论
CommentApi.getReplies获取指定评论的回复
CommentApi.createReply🔑在指定评论下发表回复
CommentApi.trash🔐把评论放入回收站
CommentApi.untrash🔐把评论移出回收站
CommentApi.getVoters获取评论的投票者
CommentApi.addVote🔑为评论投票
CommentApi.deleteVote🔑取消为评论的投票
CommentApi.get获取评论详情
CommentApi.update🔑修改评论
CommentApi.del🔑删除评论

举报

方法名描述
ReportApi.getList🔐获取被举报的内容列表
ReportApi.deleteMultiple🔐批量删除举报
ReportApi.getReasons🔐获取被举报内容的举报详情
ReportApi.create🔑添加举报
ReportApi.del🔐删除举报

通知

方法名描述
NotificationApi.getCount🔑获取未读通知数量
NotificationApi.readAll🔑把所有通知标记为已读
NotificationApi.getList🔑获取通知列表
NotificationApi.deleteAll🔑删除所有通知
NotificationApi.readMultiple🔑批量把通知标记为已读
NotificationApi.deleteMultiple🔑批量删除通知
NotificationApi.read🔑把一条通知标记为已读
NotificationApi.del🔑删除一条通知

图形验证码

方法名描述
CaptchaApi.generate生成新的图形验证码

邮件

方法名描述
EmailApi.send🔐发送邮件

图片

方法名描述
ImageApi.getList🔐获取图片列表
ImageApi.upload🔑上传图片
ImageApi.deleteMultiple🔐批量删除图片
ImageApi.get获取指定图片信息
ImageApi.update🔐更新指定图片信息
ImageApi.del🔐删除指定图片

数据统计

方法名描述
StatsApi.get🔐获取站点统计数据