突破数据孤岛：Wiki.js双接口实战指南

突破数据孤岛：Wiki.js双接口实战指南

【免费下载链接】wiki- Wiki.js | A modern and powerful wiki app built on Node.js 项目地址: https://gitcode.com/GitHub_Trending/wiki78/wiki-

在企业级文档管理系统中，API集成能力直接决定了系统与业务生态的融合深度。Wiki.js作为现代化Wiki平台，提供了RESTful与GraphQL双接口支持，让开发者能够灵活构建内容自动化流程。本文将通过实际场景案例，详解两种接口的调用方法与适用场景，帮助运营与开发人员快速掌握Wiki.js的数据交互能力。

API架构概览

Wiki.js采用分层API架构，将数据访问与业务逻辑解耦，形成可扩展的接口体系。核心接口层位于server/graph目录，包含查询类型定义、权限控制和数据解析三大模块。

API架构图

系统同时支持两种接口风格：

• GraphQL接口：通过单一端点提供灵活查询能力，位于server/graph/index.js
• RESTful接口：遵循资源导向设计，主要实现于server/controllers目录下的路由文件

GraphQL接口实战

GraphQL接口采用类型化查询语言，允许客户端精确指定所需数据，大幅减少网络传输量。Wiki.js的GraphQL模式定义在server/graph/schemas目录，其中页面相关操作定义于page.graphql。

认证与授权

所有GraphQL请求需通过JWT认证，可使用登录 mutation 获取令牌：

mutation {
  authentication {
    login(username: "admin", password: "password", strategy: "local") {
      jwt
      responseResult {
        succeeded
        errorCode
      }
    }
  }
}

权限控制通过指令实现，如auth.js中定义的@auth指令，在Schema中声明操作所需权限：

type PageQuery {
  single(id: Int!): Page @auth(requires: ["read:pages", "manage:system"])
}

核心查询示例

1. 获取页面列表

query {
  pages {
    list(limit: 10, orderBy: UPDATED, orderByDirection: DESC) {
      id
      path
      title
      updatedAt
      tags
    }
  }
}

2. 创建新页面

mutation {
  pages {
    create(
      title: "API集成指南"
      path: "developer/api-integration"
      content: "# API集成指南\n\n本文介绍Wiki.js接口使用方法"
      description: "Wiki.js API使用文档"
      editor: "markdown"
      isPublished: true
      isPrivate: false
      locale: "zh-CN"
      tags: ["API", "开发"]
    ) {
      responseResult {
        succeeded
        errorCode
      }
      page {
        id
        path
      }
    }
  }
}

RESTful接口应用

RESTful接口采用传统HTTP方法映射资源操作，主要路由定义在server/controllers目录下的文件中。

认证接口

用户认证通过server/controllers/auth.js实现，支持多种登录策略：

# 本地账号登录
curl -X POST http://wiki.example.com/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password","strategy":"local"}'

响应包含JWT令牌，后续请求需在Header中携带：

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://wiki.example.com/api/pages

文件上传接口

文件上传功能通过upload.js实现，支持批量上传：

curl -X POST http://wiki.example.com/u \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -F "file=@document.pdf" \
  -F "folderId=5"

系统监控接口

健康检查接口在common.js中定义，可用于监控系统状态：

curl http://wiki.example.com/healthz
# 响应: OK

接口选择策略

场景	推荐接口	优势
内容管理系统集成	GraphQL	灵活字段选择，减少请求次数
简单数据获取	RESTful	实现简单，缓存友好
批量数据操作	GraphQL	单次请求处理多资源
第三方系统集成	RESTful	兼容性好，学习成本低

常见问题解决

CORS跨域问题

在config.yml中配置允许的源域：

server:
  cors:
    enabled: true
    origin: ["https://app.example.com"]

权限不足错误

确保API密钥拥有足够权限，可在管理界面/a/system/api生成具有特定权限的令牌：

API密钥管理

查询性能优化

对于大型Wiki，建议使用GraphQL的片段功能减少冗余字段，并利用limit和offset分页获取数据：

fragment PageSummary on PageListItem {
  id
  path
  title
  updatedAt
}

query {
  pages {
    list(limit: 20, offsetPage: 2) {
      ...PageSummary
    }
  }
}

接口扩展建议

对于企业级集成需求，可通过以下方式扩展Wiki.js接口能力：

1. 自定义GraphQL解析器：在server/graph/resolvers目录添加新的解析函数
2. 中间件扩展：在server/core/middlewares中添加请求处理逻辑
3. WebHook集成：通过server/modules/extensions实现事件通知

通过合理选择接口类型与调用方式，Wiki.js能无缝融入各类业务系统，成为企业知识管理的核心枢纽。完整API文档可通过访问/graphql端点的内置Playground获取。

【免费下载链接】wiki- Wiki.js | A modern and powerful wiki app built on Node.js 项目地址: https://gitcode.com/GitHub_Trending/wiki78/wiki-