随机抽取 API 接口文档

?接口概览

功能说明：从学生池中随机抽取学生，支持按年级、班级筛选，支持是否允许重复抽取。

返回格式：JSON，Content-Type: application/json; charset=utf-8

频率限制：每个 IP / 用户每分钟最多 5 次请求

D随机抽取接口

参数名	类型	必填	默认值	说明
`count`	int	必填	-	抽取个数，正整数，最大 200
`allow_repeat`	string/int	选填	`false`	不传入时默认不允许重复；传 `true`/`1` 允许重复
`grade`	string	选填	-	年级筛选，为空不限制
`class_num`	string	选填	-	班级筛选，为空不限制

POST

/school/luckydraw/api.php

count 必填

1~200

allow_repeat

grade

class_num

班级号

请求体 / Query String

cURL 命令

等待发送

点击「发送请求」查看返回结果

!错误码说明

message	说明
`请先登录`	未登录状态
`抽取个数必须为正整数`	count 参数缺失或无效
`单次抽取个数不能超过200`	count 超过上限
`操作过于频繁，请 X 秒后再试`	触发频率限制（QPS=5）
`没有符合条件的学生`	筛选后无匹配学生
`符合条件的学生仅有 N 人，不足以抽取 M 个...`	不允许重复时人数不足

R抽取规则

不允许重复时：已抽中的学生不会再次被选中
允许重复时：同一个学生可能被多次抽中
自动记录：每次抽取后会自动更新学生的被抽中次数

T测试接口

用于外部功能调用测试，验证接口连通性和延时。不查数据库、不消耗频率限制。

字段	类型	说明
`success`	bool	固定为 `true`
`message`	string	固定为「测试成功」
`count`	int	固定为 `0`
`data`	array	空数组
`timestamp`	float	服务器端高精度时间戳，可用于计算网络延时

GET

/school/luckydraw/api.php?action=test

cURL 命令

curl "/school/luckydraw/api.php?action=test"

等待发送

点击「发送请求」查看返回结果

S代码示例

JavaScript (fetch)

// GET 请求 - 抽取3人
fetch('/school/luckydraw/api.php?count=3&grade=2024')
    .then(res => res.json())
    .then(data => {
        if (data.success) {
            console.log('抽中:', data.data.map(s => s.name).join(', '));
        } else {
            console.error(data.message);
        }
    });

Bash (cURL)

# 抽取3人，不重复
curl "/school/luckydraw/api.php?count=3"

# 抽取5人，允许重复，限定年级
curl "/school/luckydraw/api.php?count=5&allow_repeat=true&grade=2028"

# POST 方式
curl -X POST -d "count=2&grade=2028" "/school/luckydraw/api.php"