APITable 内部服务通知接口（InternalServiceNotificationInterfaceApi）深度解析与实战调用指南

APITable 内部服务通知接口InternalServiceNotificationInterfaceApi深度解析与实战调用指南【免费下载链接】apitable APITable, an API-oriented low-code platform for building collaborative apps and better than all other Airtable open-source alternatives.项目地址: https://gitcode.com/apitable/apitable本文是 APITable 开源仓库中packages/api-client/InternalServiceNotificationInterfaceApi.md所描述的内部服务通知接口Internal Service Notification Interface的完整技术指南。该接口以POST /internal/notification/create为唯一端点用于以无鉴权方式向指定用户、成员或组织单元批量发送站内通知消息是 APITable 后端各业务模块如成员提及、记录评论、空间管理事件等与玩家通知中心Player Notification Center之间的统一投递通道。读完本文你将掌握该接口的完整请求模型、每个字段的取值与默认行为、基于生成型 TypeScript 客户端与原生 HTTP 的调用方式以及从 Controller 到通知模板分发、再到多端站内/邮件/移动端/浏览器触达的底层实现原理。一、接口概览该接口的 OpenAPI 描述由后端接口自动生成并打包在packages/api-client包中完整的 API 文档即 InternalServiceNotificationInterfaceApi.md对应的自动生成实现为 InternalServiceNotificationInterfaceApi.ts。项目值方法名生成客户端create4HTTP 方法POST路径/internal/notification/create基准地址Base URLhttp://backend/api/v1请求体ArrayNotificationCreateRoJSON 数组返回类型ResponseDataVoid鉴权无需鉴权No authorization requiredContent-Typeapplication/jsonAccept*/*从后端路由注册看该端点定义于 InternalNotifyController.java控制器类通过ApiResource(path /internal/notification)声明路径前缀create方法通过PostResource(path /create, requiredLogin false)声明具体子路径与免登录属性——这正是文档中标注无需鉴权的根因。注意该接口属于Internal命名空间是面向 APITable 内部服务即服务间通信的接口而非面向终端用户的开放 API。二、请求模型 NotificationCreateRo 字段详解请求体是一个NotificationCreateRo对象数组模型定义在 NotificationCreateRo.ts生成版与 NotificationCreateRo.java服务端版。全部字段如下字段类型必填默认值说明toUserIdArraystring否—被通知用户 ID 列表toMemberIdArraystring否—被通知成员 ID 列表与用户 ID 二选一使用toUnitIdArraystring否—被通知组织单元Org UnitID 列表与用户 ID 二选一使用fromUserIdstring否0发送通知的用户 ID系统发起的通知固定为0nodeIdstring否null关联节点 ID如数据表节点nod10spaceIdstring否null关联空间 ID如spcHKrd0liUcltemplateIdstring是—通知模板 ID决定文案、接收对象标签to_tag与触达渠道bodyJSONObject否—通知附加内容结构见下文extras 与 toastversionstring否—版本号如v0.12.1.release用于兼容性控制expireAtstring否—过期时间毫秒级时间戳字符串如1614587900000notifyIdstring否null通知 ID可用于消息去重/定位需要注意三个要点templateId是唯一必填字段。服务端在NotificationCreateRo上通过NotBlank注解强制校验见 NotificationCreateRo.java缺省时请求会直接校验失败。接收对象三选一toUserId、toMemberId、toUnitId三个列表互斥或按需组合实际取哪些目标取决于模板的to_tag见第四节服务端会根据模板决定走用户通知还是成员通知路径。fromUserId默认0服务端 Java 模型中直接初始化为0NotificationCreateRo.java表示系统账号发出的通知。三、完整调用示例3.1 使用生成型 TypeScript 客户端packages/api-client是基于 OpenAPI Generator 生成的 TypeScript/JavaScript 客户端fetch 实现其构建与使用方式见 README.md。以下为原文档中的官方示例并补充了字段注释import { } from apitable/api-client; import * as fs from fs; const configuration .createConfiguration(); const apiInstance new .InternalServiceNotificationInterfaceApi(configuration); let body: .InternalServiceNotificationInterfaceApiCreate4Request { // ArrayNotificationCreateRo通知创建请求对象数组可一次批量投递多条 notificationCreateRo: [ { toUserId: [toUserId_example], // 被通知用户 ID 列表 toMemberId: [toMemberId_example], // 被通知成员 ID 列表与用户 ID 二选一 toUnitId: [toUnitId_example], // 被通知组织单元 ID 列表与用户 ID 二选一 fromUserId: 1261273764218, // 发送者用户 ID系统通知传 0 nodeId: nod10, // 关联节点 ID spaceId: spcHKrd0liUcl, // 关联空间 ID templateId: tplxx, // 必填通知模板 ID body: { key: {} }, // 附加 JSON 内容extras / toast version: v0.12.1.release, // 版本号 expireAt: 1614587900000, // 过期时间毫秒 notifyId: 1614587900000, // 通知 ID }, ], }; apiInstance.create4(body).then((data: any) { console.log(API called successfully. Returned data: data); }).catch((error: any) console.error(error));生成的请求工厂方法create4位于 InternalServiceNotificationInterfaceApi.ts它将请求序列化为ArrayNotificationCreateRo的 JSON 数组设置Accept: application/json, */*;q0.8与Content-Type: application/json并以POST发往/internal/notification/create。3.2 使用原生 HTTPcurl不依赖生成客户端时可直连后端接口curl -X POST http://backend/api/v1/internal/notification/create \ -H Content-Type: application/json \ -d [ { toUserId: [1261273764218], fromUserId: 0, nodeId: nod10, spaceId: spcHKrd0liUcl, templateId: tplxx, body: { extras: { viewId: viwrdXGTaiifG, recordIds: [rec5ckjeq843t] } } } ]3.3 响应结构返回类型为ResponseDataVoid即通用响应包装code/message/datadata为空。响应处理逻辑见 InternalServiceNotificationInterfaceApi.ts状态码说明200OK投递成功500Internal Server Error服务端异常如模板校验失败、批量插入失败四、后端处理链路与通知模板分发原理理解该接口的进阶用法需要读懂其后端调用链。完整链路为InternalNotifyController.create → IPlayerNotificationService.batchCreateNotify(ListNotificationCreateRo) → createNotify(ro) → INotificationFactory.getTemplateById(templateId) // 按模板 ID 取模板配置 → NotificationToTag.getValue(template.toTag) // 解析目标标签 → createUserNotify / createMemberNotify / createAllUserNotify各环节的源码依据控制器层InternalNotifyController.java 接收Valid RequestBody ListNotificationCreateRo调用playerNotificationService.batchCreateNotify(...)成功返回ResponseData.success()失败抛出BusinessException(insert error)。服务层PlayerNotificationServiceImpl.java 中batchCreateNotify使用Transactional(rollbackFor Exception.class)事务逐条调用createNotify任一条抛异常则整体回滚并返回false。模板解析createNotify首先通过notificationFactory.getTemplateById(ro.getTemplateId())查找模板模板不存在时仅记录错误日志并跳过该条随后将模板的toTag转换为NotificationToTag枚举据此分流到三种投递路径见 PlayerNotificationServiceImpl.java。4.1 NotificationToTag 目标标签toTag是模板配置中决定发给谁的关键字段枚举定义在 NotificationToTag.java枚举值原始值归属路径含义USERSusers用户通知发给指定用户 IDMYSELFmyself用户通知发给发送者本人ALL_USERSall_users全量用户发给全平台所有用户MEMBERSmembers成员通知发给指定成员ALL_MEMBERSall_members成员通知发给空间全部成员SPACE_ADMINSspace_admins成员通知发给空间管理员SPACE_MEMBER_ADMINSspace_member_admins成员通知发给空间成员管理员SPACE_MAIN_ADMINspace_main_admin成员通知发给空间主管理员这意味着即便请求中同时传了toUserId/toMemberId/toUnitId最终投递目标仍以模板的to_tag为第一优先级判定依据toUserId等字段只是为USERS/MEMBERS类模板提供具体目标集合。4.2 通知模板配置体系所有可用模板集中定义在 sysconfig/notification.json由 NotificationConfigLoader.java 加载为 NotificationTemplate.java 模型。一个典型模板如assigned_to_groupassigned_to_group: { can_jump: true, format_string: space_assigned_to_group, id: assigned_to_group, is_browser: true, is_component: true, is_mobile: true, is_mail: true, is_notification: true, mail_template_subject: assignedToGroup, notifications_type: member, to_tag: members, url: /org }模板字段与NotificationTemplate模型一一对应含义如下字段说明id模板 ID即请求中的templateIdto_tag目标标签见 4.1 节format_stringi18n 文案键用于渲染通知正文is_notification是否在通知中心展示站内通知is_mobile是否发送移动端App/小程序通知is_browser是否发送浏览器通知is_mail是否同时发送邮件配mail_template_subjectis_component是否以组件化形式渲染前端 UI 组件can_jump是否可跳转配url如/workbench、/orgnotifications_type通知分类system/space/member/record等frequency频控参数防止同一事件高频骚扰如add_record_out_of_limit设为1同一 JSON 文件还包含social_templates钉钉/企业微信等 IM 平台的社交通知模板说明该接口背后不仅是站内信还具备多端触达能力。五、body.extras 与 toast 参数说明body字段虽然是可选的JSONObject但它承载了通知跳转与前端弹窗展示的关键数据。其约定结构定义在 NotificationConstants.java{ extras: { viewId: 视图 ID, recordIds: [记录 ID 1, 记录 ID 2], toast: { allowPrev: false, // 页面切换时是否销毁已有 toast默认 false duration: 0, // 自动关闭延迟秒0 表示不自动关闭 msg: 必须发送的消息内容, // 富文本消息内容 closable: false, // 是否有关闭按钮默认 false reloadBtnText: 点击刷新页面 // 刷新按钮文案空串或不传则不显示 } } }官方示例值BODY_REQUEST_EXAMPLE{ extras: { viewId: viwrdXGTaiifG, recordIds: [rec5ckjeq843t, recETGJkQHmbR], toast: { allowPrev: false, duration: 0, msg: rich text message content, closable: false, reloadBtnText: click here to refresh the page } } }其中extras常用于携带业务上下文视图viewId、记录recordIds、涉及成员involveMemberId、空间/团队名称等均见NotificationConstants中定义的常量键供通知中心渲染跳转锚点toast则用于控制前端轻提示弹窗的交互行为。六、响应体 ResponseDataVoid 与错误处理成功HTTP 200返回ResponseDataVoid包装data为null服务端batchCreateNotify全部成功后由 Controller 返回ResponseData.success()。校验失败请求体非 JSON 数组、或数组内某元素缺少templateId时Valid校验直接拦截。业务失败模板 ID 不存在时该条被跳过仅日志记录批量过程中任意一条异常会触发整体事务回滚此时接口返回 500对应客户端生成代码中isCodeInRange(500, ...)分支抛出ApiException见 InternalServiceNotificationInterfaceApi.ts。实战建议templateId务必使用 sysconfig/notification.json 中实际存在的模板 ID否则通知会被静默丢弃批量投递时注意单次规模服务层定义了NOTIFY_LIMIT 100的常量见 PlayerNotificationServiceImpl.java从源码结构可以推断其与单次通知数量上限控制相关生产调用应避免一次性提交超大数组该接口无需登录态仅应部署于可信的内部网络/服务间调用场景切勿直接暴露到公网。七、总结InternalServiceNotificationInterfaceApi是 APITable 面向服务间通信的系统级消息投递口它以一个POST /internal/notification/create端点承接任意数量的NotificationCreateRo通过templateId驱动模板配置由to_tag决定目标群体用户/成员/全量/管理员并依据模板开关把消息分发到站内通知、邮件、移动端与浏览器等渠道。理解其字段语义、模板体系与body.extras约定即可在自建集成中精准复现 APITable 原生的消息触达行为。【免费下载链接】apitable APITable, an API-oriented low-code platform for building collaborative apps and better than all other Airtable open-source alternatives.项目地址: https://gitcode.com/apitable/apitable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考