erupt-data-notion 实战指南:用注解把 Notion 数据库接入 Erupt 管理后台

原创2026-10-14 18:54:111,934 阅读
文章标签:后端低代码认证鉴权人工智能大模型AI AgentRAG

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 与源码实现,接入时需特别注意:

  1. 主键留空:pageId 由 Notion 在新增时分配并回填,表单中不要填写;primaryKeyCol 必须正确声明,否则编辑 / 删除 / 下钻无法定位页面。
  2. 删除是软删除:删除操作即归档,归档页面从列表消失但仍存在于 Notion;误删可在 Notion 界面取消归档恢复,无法物理删除。
  3. 字段名大小写敏感:模型字段名必须与 Notion 数据库视图中显示的属性名逐字符一致。
  4. LOCAL 模式的内存边界:每次列表查询都会游标分页拉取整库(上限 5000 条)后在内存过滤排序,适合配置 / 内容规模(数百至低千条页面),不适合超大数据库;条件、排序、分页全部在内存完成,这一语义由基类 EruptBeanDataService.java 保证。
  5. 令牌缺失会直接报错:未配置 erupt.notion.token 时任何请求都会抛出 notion.token_missing,且凭据绝不能放进注解或源码。
  6. 网络层依赖外呼:所有读写都实时请求 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 的对应实现。

登录后查看全文
erupt