erupt-data-notion 实战指南:用注解把 Notion 数据库接入 Erupt 管理后台
erupt-data-notion 实战指南:用注解把 Notion 数据库接入 Erupt 管理后台
本指南讲解 Erupt 数据源插件 erupt-data-notion 的完整用法:如何通过 Spring 配置注入 Notion 集成令牌、用 @EruptNotion 把 @Erupt 模型绑定到 Notion 数据库,并基于 Notion REST API 自动获得列表、详情、新增、编辑与归档删除能力。读完本文,你将能够把一个 Notion 数据库当作与 JPA/Mongo 并列的数据源,快速为 CRM 条目、文档索引、内容日历或配置字典搭建带权限控制的后台管理界面,并理解底层属性编解码与 LOCAL 查询模式的原理与边界。
模块定位:Notion 数据库也是一种 Erupt 数据源
Erupt 是注解驱动的通用数据管理框架,其数据源通过 @EruptDataProcessor 指定。erupt-data-notion 在 pom.xml 中仅依赖 erupt-core,为 Erupt 提供 "Notion database data source" 实现:把一个 @Erupt 模型绑定到一个 Notion 数据库后,Erupt 会通过 Notion API 对页面(page)执行 list / find / add / edit / delete 操作,其中删除为归档式软删除(archive)。
该模块的定位(见模块 README 与 EruptNotionDataService.java 类注释)非常适合那些已经在用 Notion 数据库维护 CRM 记录、文档索引、内容日历或配置数据的团队——无需迁移数据,就能在同一套权限体系下获得与 JPA/Mongo 模型一致的后台视图。
一、接入准备与配置
1.1 创建内部集成并共享数据库
首先需要在 Notion 的 "My integrations" 页面创建一个内部集成(internal integration),取得形如 secret_xxxxxxxxxxxxx 的集成令牌。然后,进入目标数据库页面的右上角菜单,把该集成分享给这个数据库。集成令牌属于凭据,应存放在 Spring 配置中,绝不写入注解或源码——这一点在 EruptNotion.java 的注释中明确说明。
1.2 配置项详解
在 application.yaml 中加入如下配置:
erupt:
notion:
token: secret_xxxxxxxxxxxxx
version: "2022-06-28" # default; override to pin a different API version
# base-url: https://api.notion.com # override for a proxy
三个配置项均由 EruptNotionProperties.java 通过 @ConfigurationProperties(prefix = "erupt.notion") 绑定,并经由 EruptNotionAutoConfiguration.java 的 @EnableConfigurationProperties 注册生效:
| 配置项 | 默认值 | 说明 |
|---|---|---|
erupt.notion.token |
无(必填) | 内部集成令牌(secret_...),作为 Authorization: Bearer <token> 请求头发送;缺失时请求直接抛出 notion.token_missing 异常 |
erupt.notion.version |
2022-06-28 |
Notion API 版本,通过 Notion-Version 请求头发送,可按需固定其他版本 |
erupt.notion.base-url |
https://api.notion.com |
API 基础地址,可覆盖为代理地址 |
从源码看,token 在每次 HTTP 请求前都会校验非空(EruptNotionDataService.java),因此未配置令牌时任何操作都会立即报错而不是发出无效请求。
二、注解绑定:@EruptNotion
在模型类上添加 @EruptNotion 即可声明目标数据库:
| 属性 | 默认值 | 说明 |
|---|---|---|
databaseId |
—(必填) | Notion 数据库 ID,32 位字符,带不带连字符均可 |
databaseId 是数据库 URL 中工作区 slug 之后的那段 ID。例如数据库地址为 https://www.notion.so/workspace/abcdef0123456789abcdef0123456789?v=...,则 databaseId = "abcdef0123456789abcdef0123456789"。
该注解只声明"绑定哪个数据库",不携带任何凭据信息,与配置分离的设计保持一致。除了 @EruptNotion,模型还必须声明数据处理器:
@EruptDataProcessor(EruptNotionDataService.DATA_PROCESSOR)
DATA_PROCESSOR 常量值为 "NOTION"(见 EruptNotionDataService.java),并通过静态代码块调用 DataProcessorManager.register("NOTION", EruptNotionDataService.class) 完成自注册(DataProcessorManager.java 维护名称到 IEruptDataService 实现的映射)。后续 Erupt 运行时通过 @EruptDataProcessor 的值查表取出该 Bean,统一走数据源接口。
三、完整示例:内容日历模型
下面是一个完整的、可运行的模型示例,它把 Notion 中的"内容日历"数据库映射为 Erupt 管理对象:
@Getter
@Setter
@Erupt(name = "Content Calendar", primaryKeyCol = "pageId")
@EruptNotion(databaseId = "abcdef0123456789abcdef0123456789")
@EruptDataProcessor(EruptNotionDataService.DATA_PROCESSOR)
public class ContentEntry {
@EruptField(views = @View(title = "Page ID"))
private String pageId;
@EruptField(
views = @View(title = "Title"),
edit = @Edit(title = "Title", notNull = true, search = @Search(operator = QueryExpression.LIKE))
)
private String title;
@EruptField(
views = @View(title = "Status"),
edit = @Edit(title = "Status")
)
private String status;
@EruptField(
views = @View(title = "Author"),
edit = @Edit(title = "Author")
)
private String author;
@EruptField(
views = @View(title = "Publish On"),
edit = @Edit(title = "Publish On", type = EditType.DATE)
)
private Date publishOn;
}
关键点:
- 主键列:
@Erupt(primaryKeyCol = "pageId")声明pageId映射到 Notion 页面的id。primaryKeyCol是 Erupt.java 中@Erupt的默认属性(默认"id"),编辑、删除、下钻都必须依赖它。 - 字段名大小写敏感:模型字段名必须与 Notion 数据库视图中显示的属性名完全一致(大小写敏感),如
title、status、author、publishOn。 - Title 属性:Notion 数据库必须有且仅有一个
title类型的属性,title字段通过@Edit(notNull = true, search = @Search(operator = QueryExpression.LIKE))声明为必填且支持模糊搜索,模糊匹配在 LOCAL 模式下由内存过滤完成。
四、底层实现:五种操作的 REST 映射
EruptNotionDataService.java 继承自 EruptBeanDataService<Map<String, Object>>,只负责从 Notion 取数(data())与 CRUD 写操作,过滤、排序、分页由基类在内存中完成。五种操作与 Notion API 的对应关系如下。
4.1 List(列表查询)
调用 POST /v1/databases/{databaseId}/query 游标分页拉取整个数据库(见 data() 方法,EruptNotionDataService.java):
- 每页
page_size = 100,根据响应中的has_more/next_cursor持续翻页,直到取完; - 为防内存耗尽,设有
MAX_FETCH = 5000的上限,超过时记录警告日志并截断; - 查询模式为 LOCAL:整库数据被拉回内存后,由基类 EruptBeanDataService.queryList 统一完成条件过滤(支持 EQ / NEQ / GT / LIKE / IN 等表达式)、排序与分页,与持久化实现的语义保持一致。
因此列表场景适合配置 / 词典级数据规模(数百到低千条页面),不适合海量数据库。
4.2 Find by id(按主键查找)
调用 GET /v1/pages/{pageId} 的设计在 README 中有说明;在实现上,基类的 findDataById 会遍历 data() 返回的整库数据,按主键列等值匹配出目标行,再通过 toModel 物化为模型实例供详情 / 编辑表单使用(EruptBeanDataService.java)。
4.3 Add(新增)
调用 POST /v1/pages(addData):
- 请求体以
parent: { database_id: ... }声明父数据库; properties由模型字段按数据库 schema 重新包装(见第五节);pageId由 Notion 在创建时分配,新增表单中必须留空,保存后 Notion 返回的 page id 即为主键值。
4.4 Edit(编辑)
调用 PATCH /v1/pages/{pageId}(editData):从模型读取主键字段拼出 URL,properties 同样按 schema 编码后随请求体发送。
4.5 Delete(删除 = 归档)
调用 PATCH /v1/pages/{pageId},请求体为 {"archived": true}(deleteData)。Notion API 没有硬删除,因此这是软删除:归档页面会从列表查询结果中消失,但仍保留在 Notion 中,需要时可在 Notion 界面取消归档恢复。
4.6 传输层细节
所有请求通过 JDK HttpClient 发送(request 方法),关键行为包括:
- 超时 15 秒,自动跟随重定向;
- 每次请求携带
Authorization: Bearer <token>与Notion-Version头; - 非 2xx 响应会解析 Notion 错误体中的
message字段,与状态码一起抛给前端展示; - 错误信息经 i18n 国际化,见 erupt-notion.i18n.csv(覆盖
notion.token_missing、notion.request_failed、notion.schema_failed三条)。
五、属性编解码:Notion 属性与模型字段的映射
Notion 页面属性在 API 中是 { "type": ..., "<type>": value } 的包装结构,而模型字段是普通标量 / 列表。EruptNotionDataService 提供一对纯函数完成双向转换(源码注释标注为 "pure, unit-tested")。
5.1 读取解码(decodeProperty)
读取时把属性解包为扁平标量或列表(decodeProperty):
| Notion 属性类型 | 解码结果 |
|---|---|
title / rich_text |
拼接所有富文本片段的 plain_text 为字符串 |
number |
数字(整数返回 long,小数返回 double) |
select / status |
选项的 name 字符串,未设置为 null |
multi_select |
List<String>(各选项 name) |
checkbox |
布尔值 |
date |
start 日期字符串,如 2026-08-13 |
url / email / phone_number / created_time / last_edited_time |
原始字符串 |
people |
以 ", " 拼接的人员姓名(无姓名则用 id) |
| 其他类型 | 原始 JSON 字符串 |
5.2 写入编码(encodeProperty)
写入时按数据库 schema 把标量值重新包装(encodeProperty):
title/rich_text包装为[{ "text": { "content": ... } }]数组;number对字符串入参做数值强转——表单提交的 "150" 会被解析为 JSON 数字150而非字符串,空白或非数字输入则跳过该属性,避免被 Notion 拒绝;select/status包装为{ "name": ... },multi_select包装为[{ "name": ... }];date包装为{ "start": ... },checkbox直接传布尔;- 计算字段(
formula)以及relation/people/files等只读 / 未支持类型返回null跳过。
schema(属性名 → 类型)在首次操作数据库时通过 GET /v1/databases/{databaseId} 拉取一次,并缓存在 ConcurrentHashMap 中(schema 方法),读取失败会抛出 notion.schema_failed。
5.3 复杂类型建议配合 DataProxy 后处理
由于 relation、people、files 等类型读回来是原始 JSON 结构,README 建议:模型上先用 String / List<String> 承接,再通过 DataProxy 做后处理以提供类型化访问。DataProxy(DataProxy.java)提供了 afterFetch、beforeAdd、beforeUpdate 等钩子,可在查询结果返回前改写字段、在写入前做校验或转换,是 Notion 原始 JSON 与业务类型之间的理想适配层。
六、注意事项与踩坑指南
综合 README 的 Gotchas 与源码实现,接入时需特别注意:
- 主键留空:
pageId由 Notion 在新增时分配并回填,表单中不要填写;primaryKeyCol必须正确声明,否则编辑 / 删除 / 下钻无法定位页面。 - 删除是软删除:删除操作即归档,归档页面从列表消失但仍存在于 Notion;误删可在 Notion 界面取消归档恢复,无法物理删除。
- 字段名大小写敏感:模型字段名必须与 Notion 数据库视图中显示的属性名逐字符一致。
- LOCAL 模式的内存边界:每次列表查询都会游标分页拉取整库(上限 5000 条)后在内存过滤排序,适合配置 / 内容规模(数百至低千条页面),不适合超大数据库;条件、排序、分页全部在内存完成,这一语义由基类 EruptBeanDataService.java 保证。
- 令牌缺失会直接报错:未配置
erupt.notion.token时任何请求都会抛出notion.token_missing,且凭据绝不能放进注解或源码。 - 网络层依赖外呼:所有读写都实时请求 Notion API(15 秒超时),对 Notion 服务的可用性与网络连通性有直接依赖;
base-url可指向代理以适配受限网络。
七、单元测试:映射逻辑的正确性保障
属性编解码是纯函数,模块提供了独立的单元测试 NotionPropertyMapTest.java,无需网络与 Erupt 运行时即可运行。测试覆盖两类关键行为:
- 解码:title 富文本拼接("He" + "llo" → "Hello")、
number: 5→5L、select/status 取 name、multi_select →["a","b"]、checkbox 布尔、date 取 start,以及未设置值解包为null; - 编码:title 包装结构、数字字段对字符串入参 "150" 强转输出 JSON 数字
150(含小数 "1.5" →1.5)、空白 / 非数字输入返回null跳过、select/multi_select/checkbox 包装,以及formula等计算 / 不支持类型跳过。
这些测试直接验证了第五节映射表的语义,也是排查"字段读写类型不符"类问题时的第一参考点。
结语
erupt-data-notion 用最少的配置(一个令牌 + 一个 databaseId)把 Notion 数据库无缝接入 Erupt 的注解驱动体系,使内容运营团队可以在熟悉的 Notion 里维护数据,同时让开发者在统一后台中获得带权限的 CRUD 视图。理解其 LOCAL 查询模式、属性编解码与归档式删除这些关键设计,就能在合适的规模下放心使用,并在出现字段映射问题时快速定位到 EruptNotionDataService.java 的对应实现。