后台 API

注意事项

博客的 API 接口具有严格的参数类型安全和合法性检测，并区分大小写。请务必按照 API 文档提示的参数类型传参，否则都将会返回 409 - 请求参数不匹配 错误，包括但不限于：

1. 要求整型，实际字母
2. 枚举类匹配异常（如：要求 A 或 B，但提供 C）

一、枚举类

本系统中，除了一些必要的参数，其他的所有值都使用枚举类进行传参和接收，建议你在开发时也创建对应的枚举类，避免出现魔法值。各枚举类定义，请详见各模块接口的父文件夹文档。

二、接口响应

1.响应体结构

本系统中所有接口的响应都遵循如下基本格式：

{
    code: 200,
    errMsg: null,
    data: null
}

对应的 Kotlin 类如下：

/**
 * 响应类数据类
 * @param code 响应代码
 * @param errMsg 错误信息
 * @param data 响应数据
 */
@Serializable
data class MyResponse<T> (
    val code: Int,
    val errMsg: String?,
    val data: T?
)

2.响应代码

正常情况下，会响应以下五种 Http 状态代码：

• 200 - OK
• 409 - Conflict
• 401 - Unauthorized
• 429 - Too Many Requests
• 500 - InternalServerError

200 代表本次请求成功。
409 为自定义错误响应，本系统中所有自定义错误都将以该响应代码返回，如：账号密码错误，标签别名重复等等，通常情况下，错误的信息会在 errMsg 中，可以直接将该错误信息提示给用户。
401 为未授权请求，以下几种情况会响应该代码：

• 在未登录（请求没有附带 Token 令牌）的情况下访问有权限的接口。
• 登录过期。

429 为请求太频繁，在一些敏感的接口上会有此限制，等待一定时间恢复。
500 为未知错误，请检查服务器日志。在服务端非预期的异常都会返回该代码。

在正常使用情况下，出现 401 错误代码，就代表当前登录已经过期，需要重新登录。