探秘开发者门户

One place for everything. Accessible to everyone.

什么是开发者门户

开发者门户（developer portal）通常是一个网站或在线平台，旨在为开发者提供有关软件开发和应用程序构建的信息和资源。这些门户通常包括软件组件、资源、环境、工具、示例代码和文档等内容，这些内容可以帮助开发者更轻松地构建应用程序和软件。通过提供这些资源和工具，开发者门户可以帮助开发者缩短开发周期，减少出错频率并提高软件的质量。

为什么需要开发者门户

当公司管理的组件规模足够大时，开发团队经常会面临如下的问题：

• 这个组件的源码在哪里？负责人是谁？本周oncall是谁？
• 这个组件的使用文档在哪里？
• 哪些组件会调用这个组件的API？
• 这个服务组件有哪些依赖？它又被哪些组件所依赖？
• 这个组件还在建设中吗？还是已经应用到产品环境中了？抑或是已经过时了？
• 这个服务组件部署在哪些环境上？用的是什么版本？

正如Spotify提出的速度悖论（Speed Paradox）所言：随着公司发展速度变快，软件生态会变得更加复杂、更加碎片化，反而会限制其发展速度。

幸运的是，开发者门户可以将这些资源集中管理起来，提升开发效率。

开发者门户的核心优势

• 减少资源管理成本，提高生产力：开发者门户将每个软件与其使用资源（如文档、API、基础设施、依赖组件、release版本、部署环境等）关联起来。开发者可以快速找到所需的资源，减少软件管理成本。
• 推进责任制，增强协作：每个组件都有负责人，可以快速地响应软件相关问题，有助于组件在公司范围内的复用，避免重复造轮子，解决组件孤岛的问题。
• 一站式管理，提升组件开发效率：自助服务支持在不依赖外部团队的前提下快速构建、配置、管理组件，避免了繁杂的工作流程，提升研发效率。
• 完整生命周期管理，提升组件质量：开发者门户管理着软件的完整生命周期。模板脚手架提供了软件构建的最佳实践，使得软件在开发之初就能符合相关规范；强大的可观测性可以展示软件的完整性、成熟度、运行时关键指标，以多维度push负责人对组件进行持续打磨，提升组件质量。

开发者门户涉及的领域

• 软件目录：展示所有软件和资源的列表。
  • 追踪微服务、系统库、项目、环境、依赖等资源。易于管理大规模微服务，梳理调用关系，推动组件间复用。
  • 作为软件资源的唯一source of truth，与metrics、自助服务、自动化工作流打通。
• Scorecard：展示组件健康程度、可靠性、成熟度等指标，提供软件质量可见性。常用的指标如下：
  • 运维成熟度
    • SLO
    • 测试覆盖率
    • Oncall
  • 健康程度（告警情况）
    • 应用健康度
    • 云设施健康度
  • DORA metrics
    • 发版频率
    • 变更应用到生产环境的时间
    • 故障恢复时间
    • 变更故障率
  • 产品checklist（Operational Readiness）
• 自助服务：让开发者在不依赖外界帮助的前提下，可以自己构建和配置软件。
  • Scaffolder：开发者门户提供多种创建软件的模板，可以帮助开发者自助创建出一个软件框架。通常脚手架的提供方会集成该软件技术领域的业界规范与最佳实践，使软件在创建阶段就有较高的质量。
  • 自动化集成：开发者门户提供对常见平台（如Github、Terraform等）的自动化集成。开发者可以按需进行配置，而这些过程只需要填填表单、点点按钮即可。
  • 自定义前端组件：开发者门户提供工具与向导支持用户自定义资源表单、向导、步骤等前端组件。只需要提供schema、rules便可以构建出风格统一的前端界面。

开发者门户代表产品

目前开发者门户产品主要是Spotify开源的Backstage；基于Backstage扩展的SaaS产品Frontside、roadie等；以及公有云No-Code开发者门户Port、Cortex等。

本节简单对Backstage和Port和核心特性进行讨论。

Backstage

Backstage将服务所涉及的资源（包括代码、文档、环境、基础设施和负责人）聚拢在一处，从而使完整的开发链路流程化，统一开发体验。

核心特性

软件目录

• 软件目录将软件资源汇集在一处管理，每个团队都可以看到全局的资源视角。
• 软件目录记录着资源丰富的元信息，让开发者可以更了解软件的特性。
• 软件资源不仅限于服务，还包括库、网站、环境、pipeline等类型资源，以及他们的依赖关系。
• 每个资源都有负责人，避免了软件孤岛的出现。

软件模板

• 集成了组织内研发的最佳实践，规范地构建出一个软件应用。
• 以自助服务的方式在界面上创建一个代码仓库，并注册到软件目录中。

文档中心

• 以doc-like-code的方式编写文档，并可以实时预览效果。
• 文档与代码在一处管理，无需额外建站，易于维护。
• 文档与服务放在一起，避免一个产品一个独立的站点，易于查找。

定制化搜索

• 按需定制索引，在门户范围内全局搜索。
• 搜索可以扩展到第三方平台（如stack overflow等）。

管理K8s服务

• 专注于服务，而不是集群。
• 优化部署、服务、日志等资源的展示。
• UI与本地集群、云提供商无关，切换丝滑。

产品特点

• 开源，需要二次开发。
• 强大的插件生态大大简化外部平台集成。
• 资源定义格式采用K8s Object格式，易于理解。
• 数据模型灵活性受限，仅支持component, API, resource, system, domain 和 group六种通用资源类型。

Port

Port是一个No-Code开发者门户，构建一个单source-of-truth平台，以自助服务的方式对资源进行管理，并提供免费版与企业版两种方案。

核心特性

软件目录

• 自定义数据模型。
• 自定义视图与部件。
• 强大的资源关系图。

开发者自助服务

• 资源脚手架。
• 界面操作构建前端表单及向导。
• 外部通用平台一键集成。

RBAC准入控制

• 细粒度的资源权限控制，避免越权操作。
• 基于权限的自助工作流。
• 集成SSO。
• 审计日志记录门户事件流。

Scorecards

• 创建一个质量文化，跟踪软件的成熟度、环境健康程度、DORA指标、产品就绪状态等状态。

自动化工作流

• 快速搭建DevOps工作流，并将结果集成到软件目录中。
• 丰富的订阅机制，触发通知、告警、垃圾清理等行为。

产品特点

• 专业团队提供定制化方案。
• 公有云上提供的SaaS平台，开箱即用。
• No-Code风格，重前端，主打自助服务。
• 以蓝图描述数据模型，可以灵活定制。

产品对比

backstage vs port详细地比较了二者支持的特性及使用的侧重点。