开放 API 文档 - 大学生机房网址导航

快速开始

所有接口均为 GET 请求，无需鉴权，支持跨域（CORS）。返回统一 JSON 格式：

{ "code": 0, // 0 表示成功，非 0 表示失败（值为 HTTP 状态码） "message": "ok", // 状态说明 "data": { ... } // 业务数据（失败时为 null） }

命令行测试：

curl https://aidaohang.sxnucloud.com/api/v1/navigation

GET /api/v1/health 服务健康检查

// 响应示例
{
  "code": 0,
  "message": "ok",
  "data": {
    "status": "ok",
    "service": "lab-navigation",
    "name": "大学生机房网址导航",
    "version": "1.0.0",
    "time": "2026-08-20T02:00:00.000Z"
  }
}

GET /api/v1/health

等待请求...

GET /api/v1/settings 站点公开信息与统计

// 响应示例（部分）
{
  "code": 0,
  "data": {
    "logo_icon": "🧭",
    "site_title": "大学生机房网址导航",
    "total_categories": 6,
    "total_links": 44,
    "total_clicks": 812
  }
}

GET /api/v1/settings

等待请求...

GET /api/v1/categories 分类列表（含每个分类的链接数）

// 响应示例
{
  "code": 0,
  "data": {
    "categories": [
      { "id": 1, "name": "学习平台", "icon": "📚", "sort_order": 0, "link_count": 9 }
    ],
    "total": 6
  }
}

GET /api/v1/categories

等待请求...

GET /api/v1/links 链接列表（支持按分类过滤）

category_id

category

limit

// 响应示例
{
  "code": 0,
  "data": {
    "links": [
      {
        "id": 7, "category_id": 2,
        "title": "GitHub", "url": "https://github.com",
        "description": "全球最大代码托管平台", "icon": "🐙",
        "clicks": 156
      }
    ],
    "total": 44
  }
}

GET /api/v1/links

等待请求...

GET /api/v1/navigation 完整导航数据（分类 + 链接，一次取全）

// 响应示例
{
  "code": 0,
  "data": {
    "categories": [
      {
        "id": 1, "name": "学习平台", "icon": "📚",
        "links": [
          { "id": 1, "title": "中国大学MOOC", "url": "https://www.icourse163.org", "clicks": 98 }
        ]
      }
    ],
    "total_categories": 6,
    "total_links": 44
  }
}

GET /api/v1/navigation

等待请求...

GET /api/v1/search 站内搜索（标题 / 网址 / 描述）

q *

limit

// 响应示例（GET /api/v1/search?q=编程）
{
  "code": 0,
  "data": {
    "query": "编程",
    "results": [
      { "id": 7, "category_id": 2, "category_name": "编程开发", "title": "GitHub", "clicks": 156 }
    ],
    "total": 3
  }
}

GET /api/v1/search

等待请求...

GET /api/v1/announcements 公告列表

limit

// 响应示例
{
  "code": 0,
  "data": {
    "announcements": [
      { "id": 1, "title": "欢迎使用机房导航", "content": "本站收录了...", "link_url": "" }
    ],
    "total": 3
  }
}

GET /api/v1/announcements

等待请求...

GET /api/v1/messages 公开留言（仅已回复且公开的内容）

category

limit

// 响应示例
{
  "code": 0,
  "data": {
    "messages": [
      {
        "id": 1, "name": "小明", "content": "这个导航太好用了！",
        "reply": "谢谢支持！", "category": "学习交流",
        "view_count": 12, "like_count": 3, "favorite_count": 1
      }
    ],
    "total": 15
  }
}

GET /api/v1/messages

等待请求...

GET /api/v1/quick-entries 快捷入口列表

// 响应示例
{
  "code": 0,
  "data": {
    "quick_entries": [
      { "id": 1, "title": "学习平台", "url": "https://www.icourse163.org", "icon": "📚", "color": "#667eea" }
    ],
    "total": 6
  }
}

GET /api/v1/quick-entries

等待请求...

GET /api/v1/stats 站点统计（含热门链接 TOP10）

// 响应示例
{
  "code": 0,
  "data": {
    "categories": 6,
    "links": 44,
    "total_clicks": 812,
    "announcements": 3,
    "messages": 15,
    "users": 7,
    "top_links": [
      { "id": 12, "title": "Bilibili", "url": "https://www.bilibili.com", "clicks": 203 }
    ]
  }
}

GET /api/v1/stats

等待请求...

错误码说明

接口异常时返回 HTTP 状态码对应的错误信息，格式如下：

{ "code": 404, "message": "分类不存在", "data": null }

400 参数错误（如缺少必填参数） · 404 资源不存在 · 500 服务器内部错误

🧭 开放 API 接口文档

快速开始

错误码说明