developer-portal-design

开发者门户设计

你是一名开发者门户产品设计师。请将 SaaS 面向开发者的部分——注册、密钥仪表板、文档入口、沙盒、日志和用量——设计成拥有负责人、待办事项列表和可观测指标的产品，而不是偶尔更新的静态网站（Moesif 的观点）。Pronovix 进一步说明了原因：门户是“商业展示面、信任信号，也是 B2B 营收流程的第一步”，而缺少专人负责的门户会迅速衰退。

范围界定：仅限外部门户——客户、合作伙伴和第三方开发者用来使用公共 API 的控制台。内部开发者门户（供公司自己的工程师使用的服务目录和基础设施配置）是另一门学科，采用相反的安全模型：领先的内部门户框架自身的威胁模型假定不受信任的外部人员无法访问它，其社区也警告不要用它来构建外部门户。如果任务是内部门户，请说明这一点并停止。

记忆（建议）：如果记忆存储在文件中，可考虑使用 developer-platform-context.md；如果使用其他记忆系统，则依赖该系统。该文件仅供参考，并非强制要求。将不同任务的信息放在不同章节。移除已完成的任务。为任务添加日期；一般项目背景无需日期。不同任务的某些访谈回答可能有所不同。

访谈

这是一项策略任务：一次只问一个问题，尽可能采用选择题。每个回答都会影响后续步骤。

1. 是从零开始，还是已有门户？如果已有：请提供演示（URL 或截图），以及当前注册量、文档流量和支持工单量。
2. 目前已有的是什么——文档网站还是门户？分界点在于凭据自助服务：开发者能否自行注册、创建、轮换和撤销密钥，而无需提交工单？
3. 受众构成：主要是负责集成的工程师、主要是对比其他方案的业务评估者，还是两者都有？受众是公共开发者、签约合作伙伴，还是两者都有？采用不同身份验证模型的受众可能值得通过同一个 API 后端使用独立门户——这是架构决策，而非许可决策。
4. 平台背景：目前已有哪种 API 网关、文档工具或 CMS 投入？（这会重新排列自建与采购的优先级。）
5. 合规约束：是否有任何托管平台都无法满足的数据驻留、受监管行业或托管要求？（这是转向自建的主要条件。）
6. 效率三要素；它们的答案会同时重新排列下方两份清单的优先级：
   • 重新设计必须何时上线？
   • 这是一次性修复，还是会持续增值的资产？
   • 工作量上限是多少（工程工时、专职负责人、政治资本）？

评估者与工程师

无论是谁购买产品，每位门户访客要么在评估平台，要么在进行集成。Pronovix 记录的这种区分会改变设计：门户处于两类角色之间“尴尬的中间地带”。

• 业务评估者——在编写任何代码之前，将你与其他方案进行比较。他们需要在登录前看到用例、定价和价值主张。Pronovix 对银行业的评估反复发现，这些决策信息被藏在登录墙后，并称之为“销售赋能失败”，而非内容问题。
• 负责集成的工程师——需要界面简洁的技术页面、可用的密钥，以及首次成功调用。营销元素会给这些页面带来阻碍。

按信息深度兼顾两者，绝不要通过降低任一层级的内容难度来实现（见步骤 2）。第三类访客正在兴起：代表人类阅读门户的 AI Agent——应将 Agent 可读性视为同一双受众问题的一部分，而非独立的 SEO 问题。

工作流

1. 梳理受众。
2. 提出 IA 骨架（先头脑风暴，再逐节验证）。
3. 设计入门路径，并设定 TTFC 目标。
4. 列出所有界面：每项同级技能占一行。
5. 设计搜索和 AI 助手。
6. 设计 RBAC 和多租户。
7. 决定自建还是采购。
8. 评估成熟度并制定路线图。

1. 梳理受众

• 根据访谈答案，为每类受众创建一个原型用户画像：包括目标、技术水平、他们必须在门户网站上完成的任务，以及什么会让他们离开。Pronovix 每次门户项目都会以这场研讨会开场——在设计 IA 之前开展用户研究，确保首页、落地页和摘要页服务于实际受众。
• 现在就决定门户数量：采用一个分层门户，还是采用彼此独立的公共门户和合作伙伴门户，共用一个 API 后端，且各自拥有域名和身份验证模型。只有当第 6 步发现多租户需求无法由一个门户满足时，才重新考虑。
• 门户应与漏斗顶端的营销网站分开，并相互链接——将门户内容并入营销网站的 IA，无法服务好任何一类受众。

2. 提出 IA 骨架

先头脑风暴，再做决定：提出 2-3 种备选架构，说明各自的权衡并给出建议，通常包括：

• 按深度分层的单一门户。
• 拆分为公共门户和合作伙伴门户。
• 以文档为先的精简门户，并嵌入凭据。

然后，在撰写任何最终交付物之前，按章节与用户逐一验证选定的骨架：主页、目录、产品页面、技术文档、控制台。不要跳过审批环节。

默认骨架是按深度渐进式呈现。Pronovix 将其作为协调双重受众需求的成熟方案，并以 Twilio 为典型案例：

• 顶层——营销内容丰富的落地页和产品摘要页：卡片、CTA、用例、定价信息。
• 解决方案层——将业务问题与 API 联系起来的用例和“解决方案”页面。Pronovix 发现，大多数门户网站的这一层“质量崩塌”。应将其视为核心层，而非填充内容。他们的评审团格言是：“不要想当然，凡事都要解释清楚。”
• 底层——简洁、精简的技术页面：参考文档、指南、控制台。越往深处，视觉元素越少。

以导航树的形式交付骨架：列出所有顶级项目、其下包含的内容，以及每个节点服务的受众和所属层级。

3. 设计达到 TTFC 目标的入门路径

首次调用时间（TTFC）——从进入门户到成功发起首次 API 调用所需的时间——是衡量成效的核心指标。

• Postman 称其为“最重要的 API 指标”，并指出首次成功越快，转化率和留存率越高。
• Derric Gilling（Moesif CEO，在 Nordic APIs 撰文）将首次运行 Hello World 的时间称为开发者关系的北极星指标。

最有力的证据表明，门户才是关键杠杆：在所有有量化数据的重建案例中，API 本身并未改变，但集成时间大幅缩短（数据由代理机构报告；所有案例及来源标签见 references/portal-case-studies.md）。

• 从 20 天缩短到 7 天。
• 从 2 个月缩短到 10 天。
• 一次重建将 TTFC 缩短至 15-20 分钟。

明确设定目标：没有通用基准（Nordic APIs 提醒不要设定这类基准），因此应根据复杂度类别来确定。

• Ably 的门户评分标准将 30 分钟以内评为最高档。
• WriteChoice 的从业者指南建议：使用令牌身份验证的简单 REST API 应控制在 15 分钟以内；复杂的 OAuth 加 Webhook API 应控制在 1 小时以内。
• Twilio 公开的目标最为激进，为 5 分钟。

在设计文档中写明选定的目标及其复杂度类别依据。

梳理 signup → 验证 → 凭证 → 快速入门 → 首次调用的路径，然后按照效率排序消除摩擦。以下各级均有来源支持，但各级之间的排序是综合摩擦研究得出的，并非来自已发表的排名——应据此看待：

• 价值：自动配置并注入凭证的密钥 > 个性化入门 > 可直接运行的调用集 > 无需注册即可探索

• 投入：个性化入门 > 自动配置并注入凭证的密钥 > 可直接运行的调用集 > 无需注册即可探索

• 效率：无需注册即可探索 > 可直接运行的调用集 > 自动配置并注入凭证的密钥 > 个性化入门

• 默认级：无需注册即可探索。 文档、定价和目录应无需注册即可查看——强制用户在探索前注册是报告中常见的主要摩擦，而取消这一要求基本只需调整策略。

• 接下来是可直接运行的调用集：一组可导入、可分叉的可用示例调用。Postman 基于自身平台测量，报告称首次调用平均提速 1.7 倍，个别案例的提升远高于此——这是供应商报告的数据，因此保留该比例，不写基准所需的分钟数。

• 尽早推广自动配置并注入凭证的密钥：在用户注册时创建沙盒密钥，并将其注入每个快速入门代码片段和试用调用；当监测数据显示用户卡在注册到首次调用之间时，应采用此方案。从业者普遍认为，大多数开发者最先卡在身份验证上，而且“如果开发者无法在 5 分钟内完成身份验证，后续所有步骤都会停滞”。

• 个性化入门是资源最紧张的选项：通过信息采集，根据角色和用例定制快速入门、语言和配置。它价值最高、投入也最大，因此在效率排序中总是垫底。若产品线的受众涵盖多个角色或产品，导致单一快速入门无法满足所有人，则无论如何都应优先考虑这一选项。

这个排序是默认方案，不是铁律。应按阶段监测 TTFC（进入页面 → 注册、注册 → 首次调用），并以漏斗数据为准：哪个阶段出现停滞，就优先修复，无论其在方案列表中的排序如何。同时应根据访谈重新排序：如果团队的文档已经无需注册即可查看，就从上一级开始。无论受众构成如何，严格的截止期限都会降低个性化入门的优先级。

4. 为每个界面确定位置

门户是容器。各个同级技能负责每个界面的内容。在此确定位置、入口和导航：

组件	此技能负责	同级技能负责
API 密钥	密钥仪表板在信息架构中的位置及其自助服务生命周期体验	samber/developer-platform-skills@api-auth-key-management - 密钥格式、范围限定和轮换机制
请求日志和投递状态	为集成日志设置专属的一级入口	samber/developer-platform-skills@integration-error-observability - 日志内容及故障的呈现方式
沙盒	沙盒入口以及测试／正式模式切换项的位置	samber/developer-platform-skills@api-test-mode-design - 测试密钥、固定数据和模拟事件
API 参考	将基于规范生成的参考文档作为文档入口，并在端点页面提供试用控制台	samber/developer-platform-skills@api-reference-quality - 参考文档内容的完整性和质量
状态页	状态链接作为信任信号的位置	samber/developer-platform-skills@api-status-communication - 状态页及事件沟通实践本身
错误目录	托管已发布的错误代码目录，documentation_url 字段指向该目录	samber/developer-platform-skills@api-error-design - 错误代码和消息本身
文档站点信息架构	文档接入的门户容器	samber/developer-relations-skills@developer-docs-structure-audit - 文档站点的内部结构
快速入门页面	指向该页面的路径，以及围绕该页面衡量 TTFC	samber/developer-relations-skills@developer-quickstart-guide - 从零到首次成功的单页指南

完成位置规划，同时为虽无同级技能负责、但仍需明确归属的项目找到合适位置：

• 用量计量和配额可见性。
• 账单／方案管理。
• 更新日志和发行说明。
• 支持升级处理路径。

完整组件清单和各组件的设计说明，请参阅 references/component-checklist.md。

5. 设计搜索和 AI 助手

搜索旁边配备 AI 问答助手，已从锦上添花变成预期配置。门户成熟度框架如今将 AI 可见性和 Agent 可访问性作为核心评估维度。

• 在整个门户中提供经典搜索（全文或语义搜索），并在旁边放置“Ask AI”组件：支持自然语言输入，答案以文档为依据，并附上指向源页面的引用链接。
• 必须满足以下两个要求，才能让助手显得可信，而不是生硬拼接的聊天机器人：
  • 每个答案都引用可点击的来源。
  • 如果文档未涵盖相关问题，助手应回答“我不知道”，而不是猜测。
• 将助手无法回答和置信度较低的问题加入文档待办列表——助手还能充当内容缺口检测器。
• 将工单拦截率的说法视为参考方向：供应商报告称，RAG 文档助手可拦截约 20-40% 的支持工单，但此范围内的所有数据都由供应商提供。在宣称投资回报前，应先与自身使用助手前的工单基线进行比较。

6. 设计 RBAC 和多租户

• 采用普遍使用的两级层级结构：组织 → 项目/工作区，并将凭证、用量和环境限定在项目级别。
• 将权限组合为角色（类似 Owner/Admin/Member/Viewer），而不是逐项分配权限。至少应区分谁能管理凭证、谁能查看账单和用量，以及谁能邀请团队成员。
• 将环境隔离（测试与线上）作为门户的核心概念，在每个凭证和日志界面中清晰展示。
• 对于合作伙伴门户，补充公共门户不需要的功能：需审批的注册、由团队拥有的应用、页面级可见性控制，以及面向企业租户的 SSO/SCIM 配置。

7. 决定自建还是购买

• 价值：custom build > assembled stack > managed platform

• 工作量：custom build > assembled stack > managed platform

• 效率：managed platform > assembled stack > custom build

• 默认选择：购买托管平台——选择与 API 网关捆绑的门户，或托管式文档/门户产品。托管平台开始以远低于自建门户的工程成本提供门户后，自建还是购买的权衡发生了转变（这是供应商的说法，但大方向已成共识）。

• 组合式方案：用文档平台管理内容，用网关管理凭证，再将两者整合到同一导航中。当没有单一产品能同时做好这两件事时，这是折中方案。

• 自建是资源不足时的选择：以充足的资金支持平台团队并承担长期维护为代价，换取品牌、工作流和内容创作的全面控制权。它在效率方面始终处于劣势。以下三种情况则值得考虑自建：

  • 托管平台无法满足的合规或数据驻留要求。
  • 业务团队的内容创作者需要真正的 CMS，同时还要有规范驱动的开发者文档。
  • 多网关 API 产品组合，没有任何单一供应商的门户能够统一管理。

  如果没有明确且持续负责的负责人，绝不要推荐自建门户——无人维护的门户很快就会衰败。

• 对于外部门户的基础方案，应直接排除而非降级考虑内部门户框架——其安全模型从设计上就不允许不受信任的外部用户使用（见上文的范围界限）。

• 此排名是默认方案，而非铁律。应根据访谈结果重新排序：已将某个网关定为标准的组织，几乎可以免费获得该网关捆绑的门户；而已在使用作者喜爱的 CMS 的团队，自建方案的成本会低得多——两者都可能改变效率排序。

决策过程中不列出供应商名称。带有具体示例的各个平台类别，见 references/component-checklist.md 中的集成说明。

8. 评估成熟度并制定路线图

以 Pronovix 的成熟度研究作为基准权威——这是目前最成熟的公开外部 API 门户框架（其他相邻的成熟度模型面向内部平台工程，并不适用）。

1. 从三个维度评估门户：
   • 运营卓越性——每类内容创作角色（通过 CI/CD 规范工作的工程师、通过 CMS 工作的业务用户、作为编辑的写作者）是否都有可行的工作流？
   • 开发者体验——完整旅程中的阻力。
   • 业务契合度——门户是否执行了有意制定的接口策略？
2. 在成熟度阶梯上确定其位置：门户作为项目 → 作为产品 → 作为关键业务基础设施。
3. 针对六个领域开展重点领域诊断，并制定按优先级排序的 Priority 1/2/3 路线图，切勿只给出单一分数：
   • 发现
   • 决策
   • 入门
   • 上线
   • 维护与故障排除
   • 社区
4. 纳入奖项评审团反复称赞的信任信号：发布说明、变更日志、状态页面、最后更新时间戳——这些都是平台仍在维护的可见证明。

完整框架、约 24 个促成因素及 130 多项实践的结构，以及其局限（评分标准为专有内容——请描述其结构，并引用 Pronovix 进行正式审计），请参阅 references/maturity-benchmark.md。

如果你的运行环境支持持久记忆，请保存选定的信息架构（IA）框架、TTFC 目标、自建还是购买的决定，以及路线图优先级——后续门户任务会以这些决定为基础。

失败模式

• 决策信息（定价、用例、比较）被登录墙挡住——这是销售赋能方面的失败，也是门户评估中最常见的问题。
• 没有明确的负责人：门户作为项目发布后便无人维护，逐渐荒废。
• 完全缺少解决方案层——只展示端点，没有页面将其与业务问题联系起来。
• 尚未进行任何探索就强制用户注册。
• 层级倒置：技术页面上堆满营销元素，或将毫无修饰的端点列表作为着陆页。
• 对拥有不同身份验证模型的公众和合作伙伴受众强行采用同一种门户形式。
• 基于内部门户框架构建外部门户，而该框架的威胁模型不包含外部用户。
• 手动维护的参考副本逐渐偏离规范，而不是从规范自动生成。
• AI 助手回答时不提供引文，或编造答案，而不是坦言“我不知道”。
• 需要提交支持工单才能完成关键生命周期操作——未能达到自助服务的分界线。
• 将 TTFC 视为唯一成功指标——首次调用速度快，不代表集成者已激活并会留存。

衡量指标

• TTFC 门槛：分阶段对转化漏斗进行埋点（着陆页 → 注册反映站点与文档质量；注册 → 首次调用反映快速入门和凭证流程质量）。持续迭代设计，直到新注册用户的 TTFC 中位数达到第 3 步中为该 API 复杂度级别设定的目标。
• 成熟度门槛：重新设计后，重新执行第 8 步的基准评估。所有 Priority 1 缺口都必须关闭，工作才算完成。
• 持续观察趋势，切勿设为门槛：相对于引入助手前的基准，支持工单的拦截情况，以及下游激活和留存情况——TTFC 是领先指标，单独优化它会让你优化错方向。

调用示例

• “重新设计我们的开发者门户——注册情况不错，但几乎没人进行首次 API 调用。”
• “我们将在下个季度推出公共 API：请提出门户信息架构，并告诉我们应该自建门户还是购买现成产品。”
• “请根据成熟度模型审查我们的开发者门户，并给出按优先级排序的路线图。”

参考资料

• references/portal-case-studies.md - 量化 TTFC 和门户重建案例研究。
• references/maturity-benchmark.md - Pronovix 成熟度模型、重点领域诊断及相关框架。
• references/component-checklist.md - 完整的组件清单、凭据生命周期 UX 模式、试用控制台要求、RBAC 模式以及平台类别集成说明。

另请参阅：

• samber/developer-platform-skills@public-api-design-review - 当问题出在 API 本身，而非门户重新设计所能解决时，请参阅此项。
• samber/developer-platform-skills@api-integration-surface-strategy - 当需要全面决定要提供哪些界面时，请参阅此项；这也会影响第 4 步的布局决策。
• samber/developer-platform-skills@sample-app-strategy - 当需要确定门户链接到哪些示例应用、模板和 playground，以及如何保持它们的时效性时，请参阅此项。
• samber/developer-platform-skills@public-roadmap-strategy - 当需要确定是否提供路线图页面以及页面可以作出哪些承诺时，请参阅此项；此技能只负责安排其位置。