思源笔记 API 基础入门

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

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

---

一、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())

代码解析：

1. ​​requests.post(url, json=payload)​ ：发送 POST 请求，payload 作为 JSON 体发送。
2. ​​Authorization: Token {token}​ ：认证方式，确保 API 安全访问。
3. ​​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

---

最后

思源的 API 体系并不复杂，核心是搞清楚「读」和「写」的分工。把 SQL 当成强大的读工具，把结构化接口当作安全的写工具，你的自动化脚本和插件开发就能避开大部分坑。记住：写操作永远不要走 SQL 那条路。