🔌 标准接口
ThinkAdmin 提供完善的 API 接口开发标准，支持多种认证授权机制和数据类型。
🚀 主要功能
- 认证授权: 支持多种认证授权机制
- 多端支持: 支持微信小程序、服务号、WAP 网站等
- 安全机制: 提供安全的 token 验证机制
- 标准接口: 统一的接口数据格式和响应标准
- 文件上传: 支持文件上传和云存储对接
- 状态管理: 完善的接口状态码管理
📋 认证授权机制
授权方式
- 授权通道: 通过 API 授权通道进行身份验证
- 授权令牌: 使用 token 进行身份验证
- 多端支持: 支持多种终端类型的登录
支持的终端类型
- 微信小程序: 使用
wxapp标识 - 微信服务号: 使用
wechat标识 - WAP 网站: 使用
wap标识 - 安卓 App: 使用
android标识 - 苹果 App: 使用
iosapp标识
Token 管理
- 唯一性: 每个 API 授权通道同时只能生成一个 token
- 绑定机制: token 与终端的 user-agent 信息绑定
- 安全验证: 支持 get、post、header 三种方式提交
- 推荐方式: 建议使用 header 方式提交 token
⚙️ 接口数据标准
数据提交
- 表单方式: 支持标准 form 表单方式提交
- 数据类型: 设置为
x-www-form-urlencoded - 文件上传: 支持 base64 方式上传文件
- 云存储: 大文件建议直接对接云存储
- 参数验证: 支持参数验证和过滤
响应格式
- JSON 格式: 服务端接口响应 JSON 内容
- 固定字段: 包含 code、info、data 三个字段
- 状态码: code 为状态码
- 消息内容: info 为消息内容
- 数据内容: data 为返回数据内容
- 错误处理: 统一的错误处理机制
安全机制
- Token 验证: 基于 Token 的身份验证
- 请求签名: 支持请求签名验证
- 频率限制: 支持接口调用频率限制
- IP 白名单: 支持 IP 白名单验证
标准响应格式
{
"code": 0,
"info": "接口返回提示消息",
"data": {}
}接口数据提交
目前平台只支持标准 form 表单方式提交数据，数据类型需要设置为：x-www-form-urlencoded。如果需要上传文件，可以使用 base64 方式上传，服务端再转存为文件，上传大文件建议直接对接云存储。
服务端接口响应 json 内容，内容固定三个字段 code、info、data，其中 code 为状态码，info 为消息内容，data 为返回数据内容。
{
"code": 0,
"info": "接口返回提示消息",
"data": {}
}接口内置的返回状态码：
- 当接口状态码 code 返回 0 时，表示服务端业务执行失败，错误信息见 info 字段，数据见 data 字段。
- 当接口状态码 code 返回 1 时，表示服务端业务执行成功，提示信息见 info 字段，数据见 data 字段。
- 当接口状态码 code 返回 401 时，表示无效授权需要重新登录，错误信息见 info 字段，数据见 data 字段。
- 当接口状态码 code 返回 402 时，表示用户资料不全需要补录，错误信息见 info 字段，数据见 data 字段。
- 当接口状态码 code 返回 403 时，表示登录超时需要重新登录，错误信息见 info 字段，数据见 data 字段。
- 其他接口状态码 code 值可以根据实际情况定义，需要与接口客户端一起协商。
🔧 实际应用案例
终端 JavaScript 请求示例
基础请求示例
// 使用原生 XMLHttpRequest
var xhr = new XMLHttpRequest();
// 设置请求头
xhr.setRequestHeader('Api-Name', 'wxapp'); // 终端类型标识
xhr.setRequestHeader('Api-Token', 'your_auth_token'); // 授权TOKEN
xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
// 发送请求
xhr.open('post', 'https://your-domain.com/data/api.data/getSlider', true);
xhr.send("username=USER&password=12356");
// 处理响应
xhr.onload = function () {
if (xhr.status === 200) {
var response = JSON.parse(xhr.responseText);
if (response.code === 1) {
console.log('请求成功:', response.data);
} else {
console.error('请求失败:', response.info);
}
} else {
console.error('请求异常:', xhr.status);
}
};使用 jQuery 请求示例
// 使用 jQuery 发送请求
$.ajax({
url: 'https://your-domain.com/data/api.data/getSlider',
type: 'POST',
headers: {
'Api-Name': 'wxapp',
'Api-Token': 'your_auth_token'
},
data: {
username: 'USER',
password: '12356'
},
dataType: 'json',
success: function(response) {
if (response.code === 1) {
console.log('请求成功:', response.data);
} else {
console.error('请求失败:', response.info);
}
},
error: function(xhr, status, error) {
console.error('请求异常:', error);
}
});封装成通用方法
// 封装 API 请求方法
class ApiClient {
constructor(baseUrl, apiName, token) {
this.baseUrl = baseUrl;
this.apiName = apiName;
this.token = token;
}
request(endpoint, data = {}) {
return new Promise((resolve, reject) => {
$.ajax({
url: this.baseUrl + endpoint,
type: 'POST',
headers: {
'Api-Name': this.apiName,
'Api-Token': this.token
},
data: data,
dataType: 'json',
success: function(response) {
if (response.code === 1) {
resolve(response.data);
} else {
reject(new Error(response.info));
}
},
error: function(xhr, status, error) {
reject(new Error(error));
}
});
});
}
}
// 使用示例
const api = new ApiClient('https://your-domain.com/data/', 'wxapp', 'your_token');
api.request('api.data/getSlider', { username: 'USER', password: '12356' })
.then(data => {
console.log('请求成功:', data);
})
.catch(error => {
console.error('请求失败:', error.message);
});更多案例文档