API 概述

逍遥图库提供 RESTful API 接口，支持前后端分离开发。

基本信息

基础URL

开发环境: http://localhost:8080/api
生产环境: https://your-domain.com/api

请求格式

  • Content-Type: application/json
  • 字符编码: UTF-8

响应格式

所有接口返回 JSON 格式：

{
    "code": 0,
    "message": "success",
    "data": {
        // 返回数据
    }
}

状态码说明

code说明
0成功
400参数错误
401未认证
403无权限
404资源不存在
500服务器错误

认证方式

Token 认证

登录后获取 Token，在请求头中携带：

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

获取 Token

POST /api/auth/login
Content-Type: application/json

{
    "username": "user123",
    "password": "password123"
}

响应：

{
    "code": 0,
    "message": "success",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "expires_in": 604800
    }
}

Token 有效期

  • 默认有效期：7 天
  • 可在配置中修改

分页参数

支持分页的接口使用以下参数：

参数类型说明默认值
pageint页码1
limitint每页数量20

响应包含分页信息：

{
    "code": 0,
    "data": {
        "list": [...],
        "pagination": {
            "page": 1,
            "limit": 20,
            "total": 100,
            "pages": 5
        }
    }
}

排序参数

参数类型说明示例
sortstring排序字段create_time
orderstring排序方向desc

错误处理

错误响应格式

{
    "code": 400,
    "message": "参数错误",
    "errors": {
        "email": ["邮箱格式不正确"],
        "password": ["密码不能少于6位"]
    }
}

常见错误

HTTP 状态码说明
400请求参数错误
401未登录或 Token 过期
403没有操作权限
404资源不存在
429请求过于频繁
500服务器内部错误

频率限制

为保护系统，API 有请求频率限制：

  • 每分钟 60 次请求
  • 超出限制返回 429 错误

响应头包含限制信息：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1623456789

API 模块

模块说明文档
认证注册、登录、用户信息auth
图片图片CRUD、上传、编辑photo
相册相册管理album
用户用户主页、关注user
评论评论管理comment
管理后台管理接口admin

示例代码

JavaScript (Fetch)

// 登录获取 Token
async function login(username, password) {
    const response = await fetch('/api/auth/login', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ username, password })
    });
    const data = await response.json();
    return data.data.token;
}

// 获取图片列表
async function getPhotos(token) {
    const response = await fetch('/api/photos?page=1&limit=20', {
        headers: {
            'Authorization': `Bearer ${token}`
        }
    });
    return response.json();
}

PHP (cURL)

// 登录
function login($username, $password) {
    $ch = curl_init('http://localhost:8080/api/auth/login');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'username' => $username,
        'password' => $password
    ]));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    curl_close($ch);

    $data = json_decode($response, true);
    return $data['data']['token'];
}

Python (requests)

import requests

# 登录
def login(username, password):
    response = requests.post(
        'http://localhost:8080/api/auth/login',
        json={'username': username, 'password': password}
    )
    data = response.json()
    return data['data']['token']

# 获取图片列表
def get_photos(token):
    response = requests.get(
        'http://localhost:8080/api/photos',
        headers={'Authorization': f'Bearer {token}'},
        params={'page': 1, 'limit': 20}
    )
    return response.json()

CORS 跨域

开发环境允许所有来源的跨域请求。

生产环境需要配置允许的域名：

// config/cors.php
return [
    'allow_origin' => ['https://your-frontend.com'],
    'allow_methods' => ['GET', 'POST', 'PUT', 'DELETE'],
    'allow_headers' => ['Content-Type', 'Authorization'],
];

下一步