game_server/docs/公告接口使用示例.md

公告接口使用示例

接口概述

公告管理接口提供了完整的CRUD操作，包括创建、查询、更新和删除公告的功能。

基础路径: /api/admin/announcement

接口列表

1. 创建公告

POST /api/admin/announcement

请求体:

{
    "title": "系统维护通知",
    "content": "系统将于今晚10点进行维护，预计维护时间2小时",
    "enabled": true,
    "jumpUrl": "https://example.com"
}

响应:

{
    "success": true,
    "message": "公告创建成功",
    "id": 1
}

2. 获取公告列表（分页）

GET /api/admin/announcement/list?page=1&size=20&enabled=true

参数:

• page: 页码（默认1）
• size: 每页大小（默认20）
• enabled: 按启用状态筛选（可选）

响应:

{
    "items": [
        {
            "id": 1,
            "title": "系统维护通知",
            "content": "系统将于今晚10点进行维护，预计维护时间2小时",
            "enabled": true,
            "jumpUrl": "https://example.com",
            "createdAt": "2023-12-01T10:00:00",
            "updatedAt": "2023-12-01T10:00:00"
        }
    ],
    "total": 1,
    "page": 1,
    "size": 20
}

3. 获取公告详情

GET /api/admin/announcement/{id}

响应:

{
    "id": 1,
    "title": "系统维护通知",
    "content": "系统将于今晚10点进行维护，预计维护时间2小时",
    "enabled": true,
    "jumpUrl": "https://example.com",
    "createdAt": "2023-12-01T10:00:00",
    "updatedAt": "2023-12-01T10:00:00"
}

4. 更新公告

PUT /api/admin/announcement/{id}

请求体:

{
    "title": "系统维护通知（更新）",
    "content": "系统维护已完成",
    "enabled": false,
    "jumpUrl": null
}

响应:

{
    "success": true,
    "message": "公告更新成功"
}

5. 删除公告

DELETE /api/admin/announcement/{id}

响应:

{
    "success": true,
    "message": "公告删除成功"
}

6. 更新公告启用状态

PUT /api/admin/announcement/{id}/enabled?enabled=true

参数:

• enabled: 启用状态（true/false）

响应:

{
    "success": true,
    "message": "公告已启用"
}

7. 获取启用的公告

GET /api/admin/announcement/enabled

响应:

[
    {
        "id": 1,
        "title": "系统维护通知",
        "content": "系统将于今晚10点进行维护，预计维护时间2小时",
        "enabled": true,
        "jumpUrl": "https://example.com",
        "createdAt": "2023-12-01T10:00:00",
        "updatedAt": "2023-12-01T10:00:00"
    }
]

curl 示例

创建公告

curl -X POST http://localhost:8080/api/admin/announcement \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "title": "系统维护通知",
    "content": "系统将于今晚10点进行维护，预计维护时间2小时",
    "enabled": true,
    "jumpUrl": "https://example.com"
  }'

获取公告列表

curl -X GET "http://localhost:8080/api/admin/announcement/list?page=1&size=10&enabled=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

更新公告状态

curl -X PUT "http://localhost:8080/api/admin/announcement/1/enabled?enabled=false" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

错误处理

常见错误响应

400 Bad Request - 参数错误:

{
    "success": false,
    "message": "公告标题不能为空"
}

400 Bad Request - 字段长度超限:

{
    "timestamp": "2023-12-01T10:00:00.000+00:00",
    "status": 400,
    "error": "Bad Request",
    "message": "Validation failed",
    "errors": [
        {
            "field": "jumpUrl",
            "message": "跳转链接长度不能超过5000个字符"
        }
    ]
}

404 Not Found - 公告不存在:

{
    "timestamp": "2023-12-01T10:00:00.000+00:00",
    "status": 404,
    "error": "Not Found",
    "path": "/api/admin/announcement/999"
}

注意事项

1. 所有管理接口都需要JWT认证
2. 公告标题和内容不能为空
3. enabled 字段默认为 false
4. jumpUrl 字段可选，用于设置点击公告后的跳转链接
5. jumpUrl 字段最大长度为 5000个字符，超过此限制将返回验证错误
6. 获取启用公告的接口最多返回10条记录
7. 所有时间字段使用 ISO 8601 格式

数据库表结构

公告数据存储在 announcement 表中，包含以下字段：

• id - 主键，自增
• title - 公告标题 (VARCHAR(100))
• content - 公告内容 (TEXT)
• enabled - 启用状态 (TINYINT(1))
• jump_url - 跳转链接 (VARCHAR(5000))，可选
• belong_id - 归属ID (INT)，关联用户ID
• created_at - 创建时间 (DATETIME(3))
• updated_at - 更新时间 (DATETIME(3))