张瑞15129378030做了这些年API相关的开发，我越来越觉得“API类别”这个词被严重低估了。很多人提到API，第一反应就是“数据接口”：GET /users、POST /orders，拉个JSON回来，然后前端自己拼列表、拼详情、拼图表。但真实业务里还有一类API，它交出去的并不是数据，而是一段能直接运行的界面——也就是小部件（Widget）类API。这类API的调式套路、错误特征和普通数据接口完全不同，今天专门写一篇，把它的设计逻辑、接入步骤和排错经验一次讲清楚。
这篇文章适合两类人：一类是在做第三方平台，打算把“可嵌入组件”作为开放能力对外提供的后端/平台开发；另一类是正在集成地图、天气、客服聊天、数据报表这类外部小部件，整天跟iframe、SDK、跨域问题打交道的业务前端。无论哪一边，看完都应该能少踩几个坑。
1. 先把“小部件API”放进API分类谱系里看清楚
1.1 三类主流API类别：数据拉取、功能调用、界面交付
我习惯把API按“交付物”分成三类，这样一分类，很多设计决策就变得清晰了。
第一类是数据类API，典型代表是RESTful接口，返回JSON或XML，比如查询订单列表、获取商品详情。这类API的特点是“原数据直达”，消费方拿到数据之后，展示逻辑完全自己负责。它的优点是灵活，同一个订单接口，Web端、移动端、小程序都能用；缺点是消费方成本高，每个端都要单独处理空值、格式、状态映射。
第二类是功能类API，典型代表是支付API、短信API、文件转码API。这类API接收指令，然后执行某个动作，返回的是一个“成功/失败/任务ID”。它不负责展示，也不负责回传业务数据，核心在“命令”和“回调”。
第三类就是本文的主角：小部件类API，或者叫界面类API。它交付的不是数据，也不是命令执行结果，而是一段“可运行的用户界面”。你传给它参数，它返回一段HTML、JS或者SDK初始化配置，你把它嵌到自己的页面里，一个完整控件就出现了。
这三类API的边界不是绝对的，比如有些小部件API底层也提供数据接口，方便高级用户自己做二次渲染；但设计语义完全不同。数据API问的是“你要什么数据”，功能API问的是“你要我做什么”，小部件API问的是“你要我用什么样子出现在你的页面上”。
1.2 小部件API的技术本质：交付“可渲染的UI片段”而不是数据
理解了分类，还要理解小部件API的技术本质：它把“渲染”这个动作从消费方手里接收过来，交给服务端或SDK完成。
这句话很重要。普通数据接口把渲染消耗压在消费方，服务端只管出数据，百行JSON可能是前端十几个组件的输入源。而小部件API通常走两种技术形态：
一种是服务端渲染片段。调用方用参数请求一个URL或接口，服务端返回一段带上样式的HTML片段，消费方直接塞进容器。这种方式最直接，适合内容结构简单、交互要求不高的小部件，比如展示按钮、公告条、简单图表。坏处也很明显：复杂交互很难在一段静态HTML里承载，而且样式容易和宿主页面互相污染。
另一种是SDK/Web Component形态。接口前置步骤返回的其实是一段“脚本引导代码”，由小部件SDK接管后续资源加载和渲染。前端只需要放一个容器节点，然后初始化配置就够了。这种方式现在越来越主流，地图、客服聊天、数据分析面板基本都是这么做的。它的优点是样式隔离更好、交互能力完整、宿主不必关心小部件内部的资源加载细节；缺点是SDK体积、版本兼容性和安全边界会变成新的问题。
我比较喜欢用一个类比：数据API是卖菜谱和食材的，功能API是提供外卖配送的，小部件API是直接给你端一盘上桌的菜。菜怎么切、火候怎么控制、盘子怎么摆，都不用你操心，你只需要决定放哪张桌子上（容器）、摆到什么时候（生命周期）。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 设计一份小部件API时，最值得较真的五个决策点
如果你是平台方，准备对外提供小部件能力，下面五个点一定要在写代码之前想明白。它们决定了这份API的好用程度，也决定了后面你被多少工单骚扰。
2.1 粒度：组件边界切在哪一层
小部件API的第一个灵魂问题是粒度。同一个“天气”能力，你可以把它做成一个“城市天气卡片”，参数是城市代码；也可以拆成“温度条”“湿度条”“风力图标”三个细粒度组件，让消费方自己排列组合。
粒度设计看使用方，不看自己内部模块划分。如果目标用户是普通前端，希望“一行代码嵌入”，那就偏粗粒度，一个widget解决一个完整场景；如果目标用户是资深开发者，需要自己拼仪表盘，那就要提供细粒度原子组件，甚至暴露数据API。
一个常见的错误是把粒度切到“跟内部前端组件一样细”。内部组件可以自由调用Store、路由、工具函数，但外部消费方是没有这些内部上下文的。小部件API的粒度一旦低于业务场景，消费方就要自己去编排状态同步、事件联动，使用成本直接爆炸。
2.2 状态：谁拥有状态，谁负责同步
小部件API第二坑是状态归属不明确。天气小部件、股票行情小部件这类有数据源的小部件，状态同步方式往往设计失败。
第一种方案是“自包含状态”：小部件自己定时拉数据、自己维护加载和刷新。优点是消费方最省心；缺点是很“黑盒”，宿主想控制刷新频率、想注入自己的数据源，都不行。
第二种方案是“外部受控状态”：小部件只是一个受控组件，数据和状态由宿主通过属性或方法传入。优点是可预测、便于宿主统一管理；缺点是宿主必须自己处理异步加载、错误回退、数据缓存，等于把工作又还回去了。
实际设计中，我建议用“混合模式”：默认自包含，同时提供setData()、refresh()这类外部控制方法，再对外