当前位置：首页 > news >正文

思源笔记 API 基础入门

news 2026/5/26 16:16:31

思源的后端接口到底是怎么组织的？「数据库 API」具体又指什么？这篇就来聊聊思源的 API 体系，从基础规范到深度的数据库操作，帮你理清脉络。

API 基础规范与分类：了解内核 API 与插件 API 的本质区别。
数据库 API 的正确理解：搞清 SQL 查询与结构化接口的适用场景。
核心实践路线与注意事项：掌握安全的调用方式与避坑指南。

一、API 基础规范与体系认知

思源笔记基于 B/S 架构，其 API 主要分为两套独立的体系，理解它们的区别是使用的前提。

把内核 API 理解为「服务器接口」，插件 API 理解为「前端客户端库」，这样功能边界就清晰了。

1.1 API 体系总览

体系	核心特点	调用方式	适用场景
内核 API	基于 HTTP 的 POST 请求	`fetch`、`requests` 等	外部脚本、自动化、数据集成
插件 API	专供插件的前端 JS 库	`require('siyuan')`	思源插件内部功能扩展

1.2 内核 API 基础规范

所有数据库相关的外部接口都需要遵守以下统一规范：

基准端点：http://127.0.0.1:6806（默认端口）
HTTP 方法：全部为 POST
请求体格式：JSON，放在 body 中，Content-Type: application/json
统一返回结构：

{"code": 0,"msg": "","data": { ... }
}

code = 0 表示成功，非 0 为错误
msg 出错时包含错误信息
data 为具体返回数据，因接口而异

1.3 内核 API 的分类

内核 API 可进一步细分为两类，稳定性与应用场景各不相同。

分类	性质	稳定性	文档来源
开放 API	固定接口	高（明确固定，不会变动）	官方 API 文档
非开放 API	不稳定接口	低（可能被修改）	需查看后端源码分析

划重点： 业务开发优先使用开放 API，只有在官方文档明确支持的功能之外，才考虑分析非开放 API，并做好版本兼容准备。

二、核心概念：「数据库 API」到底指什么？

如果用一句话概括思源的“数据库 API”：

思源的“数据库 API” = SQL 查询接口( /api/query/sql ) + 一整套围绕块/文档/属性的结构化 REST API。

它并非指直接操作 SQLite 的 .db 文件，官方也不建议这样做。正确的路径是通过标准化的接口进行。

直接操作 .db 文件会导致思源笔记内部状态不一致，引发不可预知的数据混乱。所有数据操作都应通过 API 进行。

2.1 SQL 查询接口：强大的读能力

核心接口：/api/query/sql
核心用途：执行任意 SQL 语句，进行复杂的读查询与统计。
优势：灵活，支持全文统计、标签统计、时间轴分析等。
风险：写操作（INSERT, UPDATE, DELETE）极不推荐，可能导致系统损坏。

啥是 SQL 接口的适用场景？

当需要做「分析」或「统计」时，用 SQL。


# 利用 Python 调用思源 SQL API 统计所有标签import requests
import jsonurl = "http://127.0.0.1:6806/api/query/sql"
token = "your_api_token" # 避免硬编码headers = {"Content-Type": "application/json","Authorization": f"Token {token}"
}payload = {"stmt": "SELECT * FROM tags LIMIT 10"
}response = requests.post(url, headers=headers, json=payload)
print(response.json())

代码解析：

requests.post(url, json=payload) ：发送 POST 请求，payload 作为 JSON 体发送。
Authorization: Token {token} ：认证方式，确保 API 安全访问。
LIMIT 10：限制返回结果数量，避免对数据库造成过大压力。

2.2 结构化接口：安全的写能力

核心接口：/api/block/*, /api/attr/*, /api/filetree/*
核心用途：进行增、删、改操作。
优势：安全、稳定，思源内部会维护数据一致性。

为啥写操作要用结构化接口？

因为思源后端通过这些接口确保了数据和文件系统的同步，而直接 SQL 修改会绕过这些关键步骤。

写操作可以简单记成：「找块用 /api/block/，找属性用 /api/attr/，操作文件树用 /api/filetree/」。

三、实践路线与推荐做法

理解了基础体系后，推荐采用以下实践路线来安全高效地使用思源 API。

3.1 推荐操作路线

第一步：确定需求（读？写？）
第二步：读用 SQL，写用结构化 API。
第三步：小步试验，做好备份。
第四步：将 API Token 放入环境变量。

3.2 常见操作场景

场景	推荐 API	说明
全文统计	`/api/query/sql`	用 SQL 做复杂查询
创建块/文档	`/api/block/appendChildren`	结构化写操作
修改块属性	`/api/attr/setBlockAttrs`	安全修改块属性
外部知识库集成	`/api/query/sql`	配合 RAG/AI 工具

常见坑： 很多新手会用 SQL 去删除大量数据，这非常危险。这种操作一定会导致数据损坏。正确的做法是用 /api/block/removeBlock 接口。

3.3 关于 API 来源

官方文档：https://docs.siyuan-note.club/zh-Hans/reference/api/kernel/
后端路由源码：https://github.com/siyuan-note/siyuan/blob/master/kernel/api/router.go
社区资源：https://www.siyuan-note.club/apis