评估目录和自助服务操作，以确保门户始终能够满足开发人员的需求。
译自 Is Your Internal Developer Portal Maintainable?，作者 Yonatan Boguslavski。
内部开发者门户 相当新。与所有新事物一样，关于如何使用它们来完成确切任务有多种理论。有一件事每个人都同意：内部开发者门户和平台是开发者核心界面，它们需要易于维护和易于演进。毕竟，如果人员、流程和技术演进，那么为开发者服务的界面也会演进。
您如何判断您选择的门户是否可以演进并可维护？让我们对此进行全面探讨。
一个有效的内部开发者门户由以下几个元素组成：
虽然所有这些都是提供开发者体验的一部分，但我们将检查两个：
- 软件目录（服务目录）
- 自助服务操作
灵活的数据模型意味着能够在门户中建模您的工程 DNA 和用例，以：
- 反映门户中的实际软件交付生命周期 (SDLC) 和技术栈，这将使门户受到开发者和管理者的信任。
- 向门户添加用例，例如添加 AppSec 数据以支持门户中的 AppSec 标准合规性。
一个好的门户允许您在软件目录中定义、更改或添加实体类型以及这些实体类型之间的不同关系。
让我们更详细地了解这两个方面。
实体类型是资源、组件和 API 等内容。实体类型形成我们所说的软件目录的数据模型。这是软件目录用来向其用户解释 SDLC 世界的地图。地图中遗漏的内容在门户中不存在。
以下是一些您可能希望包含在门户中的实体示例：
- 云权限，以便您可以提供即时访问并更安全地工作。
- 警报，以便您可以在开发者门户中统一警报并使开发者更容易理解和解决问题。
- 事件，以便您可以支持随叫随到并为开发者提供更好的体验，并减少平均修复时间 (MTTR)。
- 漏洞，以便您可以将安全性融入每个开发人员例程。
- CI/CD，以便您可以将门户用作CI/CD 目录。
- API 数据，以便您可以将门户用于API 治理等。
能够在没有大量编码的情况下包含这些实体至关重要。
需要注意的是：具有固定数量实体类型（例如，仅 C4 模型）或需要编码才能更改它们的 portal。
与其假设实体之间存在固定的关系，您需要能够区分不同类型的依赖关系，例如将运行时云资源（计算实例）与存储资源（数据库和AWS S3 存储桶）分开。
您还希望您的门户能够指定实体之间多个不同的关系，从而在理解资源依赖关系时提供粒度和清晰度。
需要注意的是：您无法控制实体类型之间关系的门户
如果没有使用自定义实体类型或区分依赖关系的能力，您的软件目录在表示 SDLC 的关键方面时就会不足。因此，它为您的利益相关者提供的上下文和实用性较少。这一点至关重要，因为开发者不太愿意完全采用无法满足其许多需求的门户。
内部开发者门户，特别是其中的软件目录，需要保持最新。为了可维护和受信任，这需要自动进行。通过使用自动发现、实时数据更新和多种输入数据的方式，可以避免耗时的手动维护任务，确保门户信息始终是最新的和准确的。
以下是一些基本要求：
- 自动发现：目录应自动查找组织内的相关软件实体。这涉及扫描各种系统和平台，以识别和编目新的或更新的实体，而无需人工输入。没有自动发现，您将依赖开发人员的辛劳，那并不是一个好的开始。
- 协调与实时更新：该目录应定期更新其数据以匹配第三方系统等“真实来源”，以确保其准确性。这对于维护对门户的信任至关重要，并且适用于所有类型的数据，包括成本、权限、警报和漏洞。系统应纠正编录信息与资源实际状态之间的任何差异。一个主要示例是安全漏洞。目录中的 AppSec 漏洞数据必须保持最新。如果它过时，对目录的信心就会降低，并且它在提示及时采取行动方面的有效性就会丧失。因此，这削弱了门户作为警报可靠来源的作用。
-
多重导入路径：高效的数据输入应该实现自动化，尽可能避免手动输入。手动更新容易出错，给开发人员带来了不必要的负担。自动化选项包括：
- REST API：允许自动化系统和脚本直接更新目录。
- IaC（基础设施即代码）：与 IaC 工具集成，在部署过程中自动更新目录。
- Webhook：使用来自多种平台的网络挂钩来接收有关资源或配置更改的更新。
在动态、大规模环境中，这些功能对于保持编目的准确性和最新性至关重要，从而帮助简化运营和提高效率。如果没有这些功能，维护编目所需的手动工作将变得不切实际且容易出错，这会严重拖慢组织的速度。此外，如果要求开发人员手动更新编目而未向他们提供明确的好处，则可能会让他们难以使用该门户网站。
需要注意之处： 要求开发者使用 YAML 处理很多手工作业的门户。这不仅不方便，而且可能产生严重的维护性问题，并且对开发者提出了过高的要求，却没有为他们提供任何回报。
有一个倾向，就是想用插件来解决我们刚刚描述的问题。因为一个不灵活的数据模型而不能在软件目录中表示其他类型的实体（“类型”）？没问题，让我们使用插件。
然而，插件有时候会因缺乏你可能期望的功能和灵活性而使问题更加恶化，最终阻碍内部开发者门户的效用。
为什么这是一个问题？
开发者门户的目的是为开发者提供量身定制的相关抽象信息以满足他们的特定需求。要实现这一点，需要两个关键元素：
- 中心元数据存储：软件目录必须使用中心元数据存储库，其中来自核心模型或第三方工具的所有数据都可以进行上下文搜索，并用于创建信息的综合视图，例如标准记分卡等。对于某些门户，插件的数据不与核心软件目录的数据并列。没有这种集中化，插件数据就无法有效地进行搜索，从而难以回答诸如“哪些服务有开放事件？”这样的重要问题。此限制极大地降低了软件目录对任何内部开发者门户用例的实用性。无论您是在寻找成本问题还是确定哪些服务尚未准备好投入使用，您都无法在微服务级逐个搜索这些问题。
- 能够将数据抽象为您所需的方式：第三方系统所提供的数据和展示该数据的用户界面之间的联系受到限制，要想多显示或少显示一些细节，或者以不同的方式显示数据非常困难。通常，这种修改需要为插件进行一次分支，这就意味着需要具备 React 开发技能，而 DevOps 工程师中这种技能不太常见。在进行分支后，维护就成为您（和您的组织）独立的责任。
您希望您的门户能够直接为各种操作提供自助服务，例如：部署服务、回滚、触发事件、创建云资源、切换功能标志、添加机密、获取临时数据库权限和设置开发环境。
这意味着开发者不仅能够构建新服务，还能对第 2 天运营使用自助服务操作。
现有的 CI/CD 渠道（例如 GitHub 工作流、GitLab CI、Argo 工作流、AWS Lambda 和 Kubernetes 运算符）带有功能强大的开箱即用操作，可以快速可靠地执行各种任务。
例如，GitHub 工作流提供了其市集中数百个内置的操作，可用于有效管理广泛的操作。甚至对于脚手架，也可以将 Cookiecutter 库整合到 CI/CD 渠道中，以便更轻松灵活地根据指定标准自定义和创建存储库。
鉴于这些功能，内部开发者门户应专注于增强自助服务操作表单的 UI 层，并加强与这些现有 CI/CD 引擎的集成。这种方法确保了开发者的无缝体验，利用了既定工具的优势，同时提供了用户友好的界面。
需要留意的事项：只有触发自助服务的单一方式的门户，迫使你修改并替换之前的工作，并且这些门户与你当前的 CI/CD 管道的集成不紧密。
一个有效的内部开发人员门户取决于集成一个强大的软件目录和全面的自助服务操作。支持自定义实体类型并准确表示依赖关系的灵活数据模型对于创建有用且动态的目录至关重要。
自动化的实时数据提取确保信息保持最新、可靠且没有手动维护的负担。这些功能共同使开发人员能够高效地查找和使用他们需要的资源，从而营造更具生产力和精简的开发环境。
此外，虽然插件可以提供快速修复，但它们在灵活性和功能方面往往不足，可能会阻碍门户的整体有效性。相反，专注于增强自助服务操作表单的 UI 层并加强与现有 CI/CD 管道的集成，可确保开发人员获得无缝且高效的体验。
通过利用成熟工具的优势并提供用户友好的界面，组织可以构建一个开发人员门户，不仅满足当前需求，而且随着这些需求的发展而进行调整和扩展，最终提高开发人员的采用率和满意度。
在 Portal Talks 上了解有关内部开发人员门户的更多信息，6 月 26 日至 27 日，The New Stack 的 Jennifer Riggins 将主持。