API 文档

SVCG 社团管理系统 RESTful API 文档。

基础信息

  • Base URL: http://localhost:8080/api
  • 协议: HTTP/HTTPS
  • 数据格式: JSON
  • 字符编码: UTF-8

认证方式

API 使用 JWT (JSON Web Token) 进行身份认证。

获取 Token

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

{
  "username": "user@example.com",
  "password": "password123"
}

使用 Token

在请求头中包含 Authorization 字段：

Authorization: Bearer <your_jwt_token>

响应格式

成功响应

{
  "success": true,
  "data": {
    // 响应数据
  },
  "message": "操作成功"
}

错误响应

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "details": {
      // 详细错误信息
    }
  }
}

状态码

状态码说明
200请求成功
201创建成功
400请求参数错误
401未授权，需要登录
403禁止访问，权限不足
404资源不存在
409资源冲突
422数据验证失败
500服务器内部错误

API 接口列表

认证相关

方法路径说明
POST/auth/login用户登录
POST/auth/register用户注册
POST/auth/logout用户登出
POST/auth/refresh刷新 Token
POST/auth/forgot-password忘记密码
POST/auth/reset-password重置密码

成员管理

方法路径说明
GET/members获取成员列表
GET/members/{id}获取成员详情
POST/members创建成员
PUT/members/{id}更新成员信息
DELETE/members/{id}删除成员

成员资料

方法路径说明
GET/profiles获取资料列表
GET/profiles/{id}获取资料详情
POST/profiles创建资料
PUT/profiles/{id}更新资料
DELETE/profiles/{id}删除资料

活动管理

方法路径说明
GET/activities获取活动列表
GET/activities/{id}获取活动详情
POST/activities创建活动
PUT/activities/{id}更新活动
DELETE/activities/{id}删除活动

系统管理

方法路径说明
GET/health健康检查
GET/info系统信息
GET/stats统计数据

请求示例

curl 示例

# 登录获取 token
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}'

# 使用 token 访问受保护的接口
curl -X GET http://localhost:8080/api/members \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

JavaScript 示例

// 登录
const loginResponse = await fetch('/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'admin',
    password: 'password'
  })
})

const loginData = await loginResponse.json()
const token = loginData.data.token

// 获取成员列表
const membersResponse = await fetch('/api/members', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

const membersData = await membersResponse.json()

分页

对于返回列表的接口，支持分页参数：

请求参数

参数类型默认值说明
pageinteger1页码
pageSizeinteger20每页数量
sortstringid排序字段
orderstringasc排序方向 (asc/desc)

响应格式

{
  "success": true,
  "data": {
    "items": [
      // 数据列表
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}

搜索过滤

支持搜索和过滤的接口可以使用以下参数：

参数类型说明
searchstring搜索关键词
filter[field]string字段过滤
startDatestring开始日期 (YYYY-MM-DD)
endDatestring结束日期 (YYYY-MM-DD)

示例

GET /api/members?search=张三&filter[department]=技术部&page=1&pageSize=10

错误码

通用错误码

错误码说明
INVALID_REQUEST请求格式错误
VALIDATION_ERROR数据验证失败
UNAUTHORIZED未授权访问
FORBIDDEN权限不足
NOT_FOUND资源不存在
CONFLICT资源冲突
INTERNAL_ERROR服务器内部错误

业务错误码

错误码说明
USER_NOT_FOUND用户不存在
INVALID_CREDENTIALS用户名或密码错误
EMAIL_ALREADY_EXISTS邮箱已存在
USERNAME_ALREADY_EXISTS用户名已存在
TOKEN_EXPIREDToken 已过期
TOKEN_INVALIDToken 无效

速率限制

为防止滥用，API 实施了速率限制：

  • 游客: 每分钟 100 请求
  • 登录用户: 每分钟 1000 请求
  • 管理员: 无限制

超出限制时将返回 429 状态码。

版本控制

API 版本通过 URL 路径进行控制：

  • 当前版本: /api/v1/
  • 未来版本: /api/v2/

WebSocket

对于实时功能，提供 WebSocket 连接：

const ws = new WebSocket('ws://localhost:8080/ws')

ws.onopen = () => {
  console.log('WebSocket 连接已建立')
}

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log('收到消息:', data)
}

SDK 和工具

JavaScript SDK

npm install @svcg/api-client

import { SVCGClient } from '@svcg/api-client'

const client = new SVCGClient({
  baseURL: 'http://localhost:8080/api',
  token: 'your_jwt_token'
})

// 使用 SDK
const members = await client.members.list()
const member = await client.members.get(1)

Postman Collection

下载 Postman 集合：SVCG API Collection

接口详情

详细的接口文档请查看：

更新日志

v1.2.0 (2025-01-15)

  • 新增活动管理接口
  • 优化分页性能
  • 增加搜索功能

v1.1.0 (2024-12-20)

  • 新增成员资料接口
  • 支持文件上传
  • 改进错误处理

v1.0.0 (2024-11-30)

  • 初始版本发布
  • 基础认证和成员管理功能