menu MDClub JavaScript SDK 文档

MDClub JavaScript SDK 文档

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

接口文档说明

GETPUTDELETE 请求均符合幂等性。

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

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

使用详解

通过 CDN 引入 JS 文件使用

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

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

<script
  src="https://cdn.jsdelivr.net/npm/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 时,你无需考虑如何保存登录状态。

错误代码

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