教程:使用可组合PDK蓝图创建全栈应用程序 - Amazon CodeCatalyst

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

教程:使用可组合PDK蓝图创建全栈应用程序

Amazon CodeCatalyst 提供了许多不同的蓝图,以帮助您快速开始项目。使用蓝图创建的项目包括您需要的资源,包括源存储库、示例源代码、CI/CD 工作流程、构建和测试报告以及集成的问题跟踪工具。但是,有时您可能希望逐步构建项目,或者为蓝图创建的现有项目添加功能。你也可以用蓝图来做到这一点。本教程演示了如何开始使用单个蓝图,该蓝图可以奠定基础并允许您将所有项目代码存储在单个存储库中。然后,您可以方便地在初始蓝图之上添加其他蓝图,从而灵活地整合其他资源和基础架构。通过这种构造块方法,您可以满足多个项目的特定需求。

本教程展示了如何将多个AWS项目开发套件 (AWSPDK) 蓝图组合在一起,以创建一个包含 React 网站 Smithy 的应用程序API,以及要将其部署到的支持CDK基础架构。AWSAWSPDK提供了常用模式的构建块以及用于管理和构建项目的开发工具。有关更多信息,请参阅AWSPDK GitHub 源存储库

以下PDK蓝图旨在相互配合使用,以可组合的方式构建应用程序:

  • Monorepo-创建一个根级项目,用于管理 monorepo 中项目之间的相互依赖关系。该项目还提供构建缓存和依赖关系可视化。

  • Type Sa@@ fe API-创建API可以在 SmithyOpen API v3 中定义的,并管理构建时代码的生成,以允许您以类型安全API的方式实现和与之交互。提供一种CDK结构,用于管理将您的部署API到 API Gateway 并配置自动输入验证。

  • Cloudscape React 网站 ——创建一个基于 React 的网站,使用 Cloudscape 构建,该网站预先集成了 Cognito Auth 和(可选)你创建的API,这使你能够安全地呼叫你的网站。API

  • 基础架构-创建一个项目,用于设置部署应用程序所需的所有CDK相关基础架构。它还经过预配置,可以在每次构建时根据您的CDK代码生成图表。

  • DevOps-创建与AWS项目开发套件 (AWSPDK) 中的构造兼容 DevOps 的工作流程。

本教程还包括有关如何查看已部署的应用程序、邀请其他用户使用该应用程序以及如何使用拉取请求对代码进行更改的步骤,拉取请求在合并拉取请求时会自动生成并部署到关联AWS账户中的资源。

当您创建由PDK蓝图组成的项目时,您的项目是使用 CodeCatalyst 项目中的以下资源创建的:

  • 配置为 monorepo 的源存储库。

  • 一种工作流程,它运行静态代码分析和许可证检查,并在对默认分支进行更改时生成和部署示例代码。每次更改代码时,都会生成架构图。

  • 议题板和待办事项列表,可用于计划和跟踪工作。

  • 带有自动报告的测试报告套件。

先决条件

要创建和更新项目,必须按以下方式完成中的设置并登录 CodeCatalyst任务:

第 1 步:创建 monorepo 项目

PDK-Monorepo 蓝图开始,创建作为基础的monorepo代码库,允许您添加其他蓝图。PDK

使用 PDK-Monorepo蓝图创建项目

  1. 打开 CodeCatalyst 控制台,网址为 https://codecatalyst.aws/

  2. 在 CodeCatalyst 控制台中,导航到要在其中创建项目的空间。

  3. 在空间控制面板上,选择创建项目

  4. 选择 “从蓝图开始”。

  5. 选择 PDK-Monorepo 蓝图,然后选择下一步。

  6. 在 “为项目命名” 下,输入要分配给项目的名称及其关联的资源名称。该名称在空间内必须是唯一的。

  7. 在 “项目资源” 下,执行以下操作:

    1. 在 “主要编程语言” 下,选择要用来开发项目代码的语言。你可以从 TypeScript Java 或 Python 中进行选择。

    2. 选择代码配置

    3. 源存储库文本输入字段中,输入将创建新存储库的源存储库的名称,或者从现有的链接存储库中进行选择。现有存储库必须为空。有关更多信息,请参阅 链接源存储库

    4. (可选)从 Pack age Manager 下拉菜单中,选择软件包管理器。只有在您选择 TypeScript 作为主要编程语言时,才需要这样做

  8. (可选)要预览将根据您选择的项目参数生成的代码,请从 “生成项目预览” 中选择 “查看代码”。

  9. (可选)从蓝图的卡片中选择查看详细信息以查看有关蓝图的特定详细信息,例如蓝图架构概述、所需的连接和权限以及蓝图创建的资源类型。

  10. 选择 “创建项目” 来创建您的 monorepo 项目。创建的根级项目管理 monorepo 中项目之间的相互依赖关系,并提供构建缓存和依赖项管理。

    有关项目蓝图的更多信息,请参阅使用 CodeCatalyst 蓝图创建综合项目

PDK-Monorepo 蓝图仅生成项目的基础。要使用蓝图创建可行的应用程序,你需要添加其他PDK蓝图,例如 Type Safe、Cloudscape React Website API、Infrastructure 或。 DevOps在下一步中,您将向项目添加 Type Saf API e。

第 2 步:在项目中添加 Type Saf API e

PDK-Type Safe API 蓝图允许你API使用 Smithy 或 OpenAI v3 来定义。它根据你的API定义生成运行时包,其中包括用于与你交互的客户端API和用于实现你的API服务器端代码。蓝图还会为每个API操作生成一个具有类型安全的CDK构造。您可以将蓝图添加到现有的 PDK monorepo 项目中,为该项目添加API功能。

添加 PDK-Type Safe API 蓝图

  1. 在 monorepo 项目的导航窗格中,选择蓝图,然后选择添加蓝图。

  2. 选择 PDK-Type Safe API 蓝图,然后选择 “下一步”。

  3. 配置蓝图下,配置蓝图参数:

    • 模型语言下,选择定义API模型的语言。

    • 命名空间文本输入字段中,输入您的命名空间API。

    • API名称文本输入字段中,输入您的姓名API。

    • 在 “CDK语言” 下,选择您首选的语言来编写要部署CDK的基础架构。API

    • 选择 Handler 语言下拉菜单,然后选择要为API操作实现处理程序的语言。

    • 选择文档格式下拉菜单,然后选择生成API文档所需的格式。

  4. 在 “代码更改” 选项卡中,查看建议的更改。拉取请求中显示的差异显示了创建拉取请求时您的项目所做的更改。

  5. 如果您对应用蓝图时将要进行的拟议更改感到满意,请选择添加蓝图

    创建拉取请求后,您可以添加评论。可以将评论添加到拉取请求或文件中的各个行中,也可以添加到整个拉取请求中。您可以使用@符号和文件名来添加指向资源(例如文件)的链接。

    注意

    在拉取请求获得批准并合并之前,蓝图才会被应用。有关更多信息,请参阅查看拉取请求合并拉取请求

  6. 在 “状态” 列中,选择 “PDK-Type Safe” API 蓝图行的 “待处理拉取请求”,然后选择已打开的拉取请求的链接。

  7. 选择 “合并”,选择您的首选合并策略,然后选择 “合并” 以合并应用蓝图中的更改。

    合并拉取请求后,将在您的 monorepo 项目中生成一个新packages/apis/mypdkapi文件夹,其中包含您配置的 Type Safe 的所有API相关源代码。API

  8. 在导航窗格中,选择 Blueprin ts 以确认 PDK-Type Safe状态API显示为最新

第 3 步:为项目添加 Cloudscape React 网站

PDK-Cloudscape React 网站蓝图生成一个网站。您可以关联一个可选参数(Type SafeAPIs)来自动配置您的网站以设置经过身份验证的类型安全客户端,还可以关联一个交互式API浏览器来测试您的各种API客户端。

添加 PDK ——Cloudscape React 网站蓝图

  1. 在 monorepo 项目的导航窗格中,选择蓝图,然后选择添加蓝图。

  2. 选择 PDK-Cloudscape React 网站蓝图,然后选择下一步。

  3. 配置蓝图下,配置蓝图参数:

    • 网站名称文本输入字段中,输入您的网站名称。

    • 选择 Type Saf e APIs 下拉菜单,然后选择要集成到网站中的API蓝图。传入会API设置经过身份验证的客户端,并添加所需的依赖项、API资源管理器和其他功能。

  4. 在 “代码更改” 选项卡中,查看建议的更改。拉取请求中显示的差异显示了创建拉取请求时您的项目所做的更改。

  5. 如果您对应用蓝图时将要进行的拟议更改感到满意,请选择添加蓝图

    创建拉取请求后,您可以添加评论。可以将评论添加到拉取请求或文件中的各个行中,也可以添加到整个拉取请求中。您可以使用@符号和文件名来添加指向资源(例如文件)的链接。

    注意

    在拉取请求获得批准并合并之前,蓝图才会被应用。有关更多信息,请参阅查看拉取请求合并拉取请求

  6. 从 “状态” 列中,选择 “PDK-Cloudscape React Webs ite 蓝图” 行的 “待处理拉取请求”,然后选择已打开的拉取请求的链接。

  7. 选择 “合并”,选择您的首选合并策略,然后选择 “合并” 以合并应用蓝图中的更改。

    合并拉取请求后,将在您的 monorepo 项目中生成一个新packages/websites/my-website-name文件夹,其中包含新网站的所有源代码。

  8. 在导航窗格中,选择蓝图以确认 Cloudscape React 网站状态显示为最新。PDK

接下来,您将添加 PDK-基础架构蓝图以生成基础架构,将您的网站部署到AWS云端。

步骤 4:生成基础架构以将应用程序部署到AWS云端

PDK-基础架构蓝图会设置一个包含所有CDK代码的软件包,用于部署您的网站和API. 默认情况下,它还提供图表生成和与原型设计工具包的一致性。

添加 PDK-基础设施蓝图

  1. 在 monorepo 项目的导航窗格中,选择蓝图,然后选择添加蓝图。

  2. 选择 PDK-基础架构蓝图,然后选择下一步

  3. 配置蓝图下,配置蓝图参数:

    • 在 “CDK语言” 下,选择要用来开发基础架构的语言。

    • 堆栈名称文本输入字段中,输入为蓝图生成的 CloudFormation 堆栈的名称。

      注意

      请记下此堆栈名称,以便在下一步中设置 DevOps 工作流程。

    • 选择 Type Saf e APIs 下拉菜单,然后选择要集成到网站中的API蓝图。

    • 选择 Cloudscape React TS 网站下拉菜单,然后选择要在基础架构中部署的网站蓝图(例如,PDK-Cloudsc ape React 网站)。

  4. 在 “代码更改” 选项卡中,查看建议的更改。拉取请求中显示的差异显示了创建拉取请求时您的项目所做的更改。

  5. 如果您对应用蓝图时将要进行的拟议更改感到满意,请选择添加蓝图

    创建拉取请求后,您可以添加评论。可以将评论添加到拉取请求或文件中的各个行中,也可以添加到整个拉取请求中。您可以使用@符号和文件名来添加指向资源(例如文件)的链接。

    注意

    在拉取请求获得批准并合并之前,蓝图才会被应用。有关更多信息,请参阅查看拉取请求合并拉取请求

  6. 状态列中,为基础架构蓝图行选择待处理的拉取请求,然后选择已打开的拉取请求的链接。PDK

  7. 选择 “合并”,选择您的首选合并策略,然后选择 “合并” 以合并应用蓝图中的更改。

    合并拉取请求后,将在您的 monorepo 项目中生成一个新packages/infra文件夹,其中包含将您的项目部署到云端的基础架构。AWS

  8. 在导航窗格中,选择 Blue prints 以确认基础架构PDK状态显示为最新

接下来,您将添加 PDK- DevOps 蓝图来部署您的应用程序。

第 5 步:设置部署项目 DevOps 的工作流程

PDK- bluep DevOps rint 使用配置中指定的AWS账户和角色生成生成和部署项目所需 DevOps 的工作流程。

添加 PDK- DevOps 蓝图

  1. 在 monorepo 项目的导航窗格中,选择蓝图,然后选择添加蓝图。

  2. 选择 PDK- DevOps 蓝图,然后选择下一步

  3. 配置蓝图下,配置蓝图参数:

    • 在当前环境CDK中选择 Bootstrap

    • 堆栈名称文本输入字段中,输入要部署的 CloudFormation 堆栈的名称。这应该与在基础架构蓝图中配置步骤 4:生成基础架构以将应用程序部署到AWS云端的PDK堆栈名称相匹配。

    • 选择AWS账户连接下拉菜单,然后选择要用于资源的AWS账户。有关更多信息,请参阅 向 AWS 账户 空间添加

    • 选择用于部署应用程序的角色下拉菜单,然后选择要用于部署项目应用程序的IAM角色。

      注意

      创建IAM角色时,请将限制SourceArn为在项目设置中ProjectID找到的当前角色。有关更多信息,请参阅 了解CodeCatalystWorkflowDevelopmentRole-spaceName服务角色

    • 选择 “区域” 下拉菜单,然后选择要部署 monorepo 项目的区域。部署仅适用于存在所需AWS服务的区域。有关更多信息,请参阅按地区划分的AWS服务

  4. 在 “代码更改” 选项卡中,查看建议的更改。拉取请求中显示的差异显示了创建拉取请求时您的项目所做的更改。

  5. 如果您对应用蓝图时将要进行的拟议更改感到满意,请选择添加蓝图

    创建拉取请求后,您可以添加评论。可以将评论添加到拉取请求或文件中的各个行中,也可以添加到整个拉取请求中。您可以使用@符号和文件名来添加指向资源(例如文件)的链接。

    注意

    在拉取请求获得批准并合并之前,蓝图才会被应用。有关更多信息,请参阅查看拉取请求合并拉取请求

  6. 状态列中,为基础架构蓝图行选择待处理的拉取请求,然后选择已打开的拉取请求的链接。PDK

  7. 选择 “合并”,选择您的首选合并策略,然后选择 “合并” 以合并应用蓝图中的更改。

    合并拉取请求后,将在您的 monorepo 项目中生成一个新.codecatalyst/workflows文件夹。

  8. 在导航窗格中,选择 Blue prints 以确认 PDK-状态 DevOps显示为最新

注意

从那时起,PDK- blueprint 和 DevOpsPDK蓝图的所有后续更改都将显著减慢,因为在幕后生成锁定文件是为了确保构建和部署在将来是可重复的。它将为所有支持语言的软件包生成锁定文件。

第 6 步:确认发布工作流程并查看您的网站

完成前面的步骤后,您可以确认发布工作流程以确保项目正在构建中。

确认发布工作流程并查看您的网站

  1. 在 monorepo 项目的导航窗格中,选择 C I/CD,然后选择工作流程。

  2. 对于发布工作流程,请选择最新运行的工作流程以查看详细信息。有关更多信息,请参阅 查看单次运行的状态和详细信息

  3. 成功完成工作流程运行后,选择工作流程中的最后一个操作(例如 Deplo y-B-eta-ap-souteast 2),然后选择变量。

    PDK蓝图工作流程。
  4. 通过复制并粘贴变量表中的链接来查看已部署的网站(例如,MyPDKApiwebsiteDistributionDomain名称 XXXXX) 进入新的浏览器窗口。

    工作流程操作的变量表。

    您需要一个 Amazon Cognito 账户才能登录您的网站。默认情况下,用户池未设置为允许自行注册。

    1. 导航到 AWSCognito 控制台

    2. 用户池表中,选择与 PDK- b DevOps luep rint创建的用户池相匹配的用户池名称,该名称可在变量表中找到(例如,infracalculatebetaUserIdentityinfracalculatebetaUserIdentityIdentityPoolIdXXXXX。有关更多信息,请参阅用户池入门

      用户池由 PDK- DevOps 蓝图创建。
    3. 选择 创建用户

    4. 配置用户信息参数:

      • 在 “邀请消息” 下,选择 “发送电子邮件邀请”。

      • 用户名文本输入字段中,输入用户名。

      • 电子邮件地址文本输入字段中,输入用户名。

      • 在 “临时密码” 下,选择 “生成密码”。

    5. 选择 创建用户

    6. 导航到您为用户信息参数输入的电子邮件帐户,使用临时密码打开一封电子邮件。记下密码。

    7. 返回已部署的网站,输入您创建的用户名和收到的临时密码,然后选择登录

  5. (可选)成功完成工作流程运行后,您还可以查看生成的逻辑示意图。选择中的 “构件” 选项卡 CodeCatalyst,在 “关系图” 行中选择 “下载”,然后打开下载的文件。

    工作流程的 “构件” 选项卡。
    由PDK蓝图生成的逻辑示意图。

在项目上进行协作和迭代 PDK

项目设置完成后,您可以对源代码进行更改。您也可以邀请其他空间成员参与该项目。PDK蓝图允许您以迭代方式构建应用程序,仅在需要时添加所需的内容,同时保留对每个蓝图配置的完全控制。

第 1 步:邀请成员加入您的项目

您可以使用控制台邀请用户加入您的项目。您可以邀请空间成员或在空间之外添加姓名。

要邀请用户加入您的项目,您必须使用项目管理员或空间管理员角色登录

您无需邀请具有空间管理员角色的用户加入您的项目,因为他们已经隐式访问空间中的所有项目。

当您邀请用户加入您的项目(未分配空间管理员角色)时,该用户将显示在项目成员表格中的项目下和空间下的项目成员表中。

从 “项目设置” 选项卡邀请成员加入您的项目
  1. 导航到您的项目。

    提示

    您可以在顶部导航栏中选择要查看的项目。

  2. 在导航窗格中,选择项目设置

  3. 选择成员选项卡。

  4. 项目成员中,选择邀请新成员

  5. 键入新成员的电子邮件地址,选择该成员的角色,然后选择邀请。有关角色的更多信息,请参阅使用用户角色授予访问权限

从项目概述页面邀请成员加入您的项目
  1. 导航到您的项目。

    提示

    您可以在顶部导航栏中选择要查看的项目。

  2. 选择 “成员 +” 按钮。

  3. 键入新成员的电子邮件地址,选择该成员的角色,然后选择邀请。有关角色的更多信息,请参阅使用用户角色授予访问权限

第 2 步:创建议题以进行协作和跟踪工作

CodeCatalyst 帮助您跟踪项目中涉及的功能、任务、错误以及任何其他有问题的工作。您可以创建议题来跟踪所需的工作和想法。默认情况下,当您创建议题时,它会添加到待办事项中。您可以将问题移至图板,在那里您可以跟踪正在进行的工作。您也可以将议题分配给特定的项目成员。在此步骤中,创建一个议题以对您的PDK项目进行更改。

创建议题

  1. 打开 CodeCatalyst 控制台,网址为 https://codecatalyst.aws/

  2. 导航到你要在其中创建议题的 monorepo 项目。

  3. 在项目主页上,选择创建问题。或者,在导航窗格中选择 “问题”。

  4. 选择 “创建问题”。

    注意

    使用网格视图时,您也可以内联添加问题。

  5. 输入问题的标题。

  6. (可选)输入描述。对于此问题,请输入以下描述:a change in the src/mysfit_data.json file.。你可以使用 Markdown 来添加格式。

  7. (可选)选择问题的状态优先级估计

  8. (可选)添加现有标签或创建新标签并通过选择 + 添加标签进行添加

    1. 要添加现有标签,请从列表中选择标签。您可以在字段中输入搜索词,以搜索项目中包含该术语的所有标签。

    2. 要创建并添加新标签,请在搜索字段中输入要创建的标签的名称,然后按 Enter。

  9. (可选)通过选择 + 添加工作负责人来添加工作负责人。您可以通过选择 + 添加我来快速将自己添加为受托人。

    提示

    您可以选择将问题分配给 Amazon Q,让 Amazon Q 尝试解决问题。有关更多信息,请参阅 教程:使用 CodeCatalyst 生成式 AI 功能加快开发工作

    此功能要求为该空间启用生成式 AI 功能。有关更多信息,请参阅管理生成式 AI 功能

  10. (可选)添加现有的自定义字段或创建新的自定义字段。议题可能有多个自定义字段。

    1. 要添加现有的自定义字段,请从列表中选择该自定义字段。您可以在字段中输入搜索词,以搜索项目中包含该术语的所有自定义字段。

    2. 要创建并添加新的自定义字段,请在搜索字段中输入要创建的自定义字段的名称,然后按 Enter。然后选择要创建的自定义字段的类型并设置一个值。

  11. 选择 “创建问题”。右下角会显示一条通知:如果问题已成功创建,则会显示一条确认消息,说明问题已成功创建。如果问题未成功创建,则会显示一条包含失败原因的错误消息。然后,您可以选择 “重试” 进行编辑并重试创建问题,或者选择 “丢弃” 放弃问题。这两个选项都将关闭通知。

    注意

    在创建议题时,您无法将拉取请求与议题相关联。但是,您可以在创建拉取请求后对其进行编辑,以添加拉取请求的链接。

有关更多信息,请参阅 跟踪和组织处理问题的工作 CodeCatalyst

第 3 步:查看您的源代码库

您可以在 Amazon 中查看与项目关联的源存储库 CodeCatalyst。对于中的源存储库 CodeCatalyst,存储库的概述页面提供了该存储库中信息和活动的快速概述,包括:

  • 存储库的描述(如果有)

  • 存储库中的分支数量

  • 仓库的未处理拉取请求数量

  • 存储库的相关工作流程数量

  • 默认分支或您选择的分支中的文件和文件夹

  • 显示分支的最后一次提交的标题、作者和日期

  • 在 Markdown 中呈现的 README .md 文件的内容(如果包含任何 README .md 文件)

该页面还提供指向仓库提交、分支和拉取请求的链接,以及打开、查看和编辑单个文件的快速方法。

注意

您无法在 CodeCatalyst 控制台中查看有关链接仓库的这些信息。要查看有关链接存储库的信息,请在存储库列表中选择链接,在托管该存储库的服务中打开该存储库。

导航到项目的源存储库
  1. 导航到您的项目,然后执行以下任一操作:

    • 在项目的摘要页面上,从列表中选择所需的存储库,然后选择 “查看存储库”。

    • 在导航窗格中,选择代码,然后选择源存储库。在源存储库中,从列表中选择存储库的名称。您可以通过在筛选栏中键入部分存储库名称来筛选存储库列表。

  2. 在存储库的主页上,查看存储库的内容以及有关关联资源的信息,例如拉取请求的数量和工作流程。默认情况下,会显示默认分支的内容。您可以通过从下拉列表中选择其他分支来更改视图。

提示

您还可以通过在项目摘要页面中选择 “查看项目代码” 来快速导航到项目的存储库。

第 4 步:创建开发环境并更改代码

在此步骤中,创建一个开发环境并进行代码更改,然后将其合并到主分支中。虽然本教程将引导您完成一个简单的AWSPDK项目,但您也可以按照AWSPDK GitHub 存储库中提供的更复杂的示例进行操作。

使用新分支创建开发环境

  1. 在 monorepo 项目的导航窗格中,执行以下任一操作:

    • 选择 “概述”,然后导航到 “我的开发环境” 部分。

    • 选择 “代码”,然后选择 “开发环境”。

    • 选择 “代码”,选择 “源存储库”,然后选择要为其创建开发环境的 monorepo 存储库。

  2. IDE从下拉菜单中选择支持的。请参阅开发环境支持的集成开发环境了解更多信息。

  3. 选择克隆存储库

  4. 选择要克隆的存储库,选择在新分支中工作,在分支名称字段中输入分支名称,然后从创建分支自下拉菜单中选择要从中创建新分支的分支。

    注意

    如果您从源存储库页面或从特定的源存储库创建开发环境,则无需选择存储库。开发环境将从您从源存储库页面中选择的源存储库创建。

  5. (可选)在 “别名-可选” 中,输入开发环境的别名。

  6. (可选)选择开发环境配置编辑按钮以编辑开发环境的计算、存储或超时配置。

  7. (可选)在 Amazon Virtual Private Cloud(亚马逊VPC)(可选)中,从下拉菜单中选择要与开发环境关联的VPC连接。

    如果您的空间设置了默认值,VPC则您的开发环境将与该空间连接运行VPC。您可以通过关联不同的VPC连接来覆盖此设置。另请注意,VPC连接的开发环境不支持 AWS Toolkit。

    注意

    使用VPC连接创建开发环境时,将在其中创建一个新的网络接口VPC。 CodeCatalyst 使用关联的VPC角色与该接口进行交互。另外,请确保您的IPv4CIDR区块配置为 172.16.0.0/12 IP地址范围。

  8. 选择创建。在创建开发环境时,开发环境状态列将显示正在启动,开发环境创建完成后,状态列将显示正在运行

开发环境运行后,您可以在中使用生成的示例应用程序, CodeCatalyst 方法是使用拉取请求对代码进行更改,拉取请求将在合并拉取请求时自动生成并部署到关联AWS账户中的资源。monorepo 出售开发文件,因此所有必需的全局依赖项和运行时都会自动出现。

更改项目中的代码

  1. 在开发环境的工作终端中,导航到您的 monorepo 项目,然后通过运行以下命令安装项目依赖项:

    npx projen install
  2. 导航到packages/apis/mypdkapi/model/src/main/smithy/operations/say-hello.smithy,其中定义了示例API操作。在本教程中,您将构建一个将两个数字相加在一起的简单Calculate操作。更改代码以定义此操作,包括其输入和输出。

    示例:

    $version: "2" namespace com.aws @http(method: "POST", uri: "/calculate") @handler(language: "typescript") operation Calculate { input := { @required numberA: Integer @required numberB: Integer } output := { @required result: Integer } }

    @handler该特征告诉 Type SafeAPI,您将以写入的 Lamb AWS da 处理程序的形式实现此操作。 TypeScriptType Safe API 将为此操作生成一个存根供你在中实现。 TypeScript该@required特征已添加,这意味着它将在运行时由部署的API网关强制执行。有关更多信息,请参阅 Smithy 文档

  3. 使用与您的代码更改一致/say-hello.smithy的文件名来重命名(例如,calculate.smithy)。

  4. 导航到packages/apis/mypdkapi/model/src/main/smithy/main.smithy,然后对代码进行更改以连接操作。您可以/calculate.smithy通过在此文件的operations字段中列出中定义的Calculate操作来公开该操作。

    示例:

    $version: "2" namespace com.aws use aws.protocols#restJson1 /// A sample smithy api @restJson1 service MyPDKApi { version: "1.0" operations: [Calculate] errors: [ BadRequestError NotAuthorizedError InternalFailureError ] }
  5. 通过运行以下命令来生成更改:

    npx projen build
    注意

    或者,您可以传入--parallel X标志,它将在X内核之间分配构建。

    由于添加了@handler特征,因此将在构建完成后生成以下文件:

    • /packages/apis/mypdkapi/handlers/typescript/src/calculate.ts

    • /packages/apis/mypdkapi/handlers/typescript/test/calculate.test.ts

  6. 导航到packages/apis/mypdkapi/handlers/typescript/src/calculate.ts,然后对代码进行更改。此文件是为调用的服务器处理程序API。

    import { calculateHandler, CalculateChainedHandlerFunction, INTERCEPTORS, Response, LoggingInterceptor, } from 'mypdkapi-typescript-runtime'; /** * Type-safe handler for the Calculate operation */ export const calculate: CalculateChainedHandlerFunction = async (request) => { LoggingInterceptor.getLogger(request).info('Start Calculate Operation'); const { input } = request; return Response.success({ result: input.body.numberA + input.body.numberB, }); }; /** * Entry point for the AWS Lambda handler for the Calculate operation. * The calculateHandler method wraps the type-safe handler and manages marshalling inputs and outputs */ export const handler = calculateHandler(...INTERCEPTORS, calculate);
  7. 导航到该/packages/apis/mypdkapi/handlers/typescript/test/calculate.test.ts文件,然后对代码进行更改以更新单元测试。

    示例:

    import { CalculateChainedRequestInput, CalculateResponseContent, } from 'mypdkapi-typescript-runtime'; import { calculate, } from '../src/calculate'; // Common request arguments const requestArguments = { chain: undefined as never, event: {} as any, context: {} as any, interceptorContext: { logger: { info: jest.fn(), }, }, } satisfies Omit<CalculateChainedRequestInput, 'input'>; describe('Calculate', () => { it('should return correct sum', async () => { const response = await calculate({ ...requestArguments, input: { requestParameters: {}, body: { numberA: 1, numberB: 2 } }, }); expect(response.statusCode).toBe(200); expect((response.body as CalculateResponseContent).result).toEqual(3); }); });
  8. 导航到该/packages/infra/main/src/constructs/apis/mypdkapi.ts文件,然后对代码进行更改,以便在您的CDK基础架构中为该Calculate操作添加集成。该API构造具有 integrations 属性,你可以在其中传入之前添加的实现。由于您使用的是 Smithy 模型中的@handler特征进行Calculate操作,因此您可以使用预先配置的生成的CalculateFunctionCDK构造来指向您的处理程序实现。

    示例:

    import { UserIdentity } from "@aws/pdk/identity"; import { Authorizers, Integrations } from "@aws/pdk/type-safe-api"; import { Stack } from "aws-cdk-lib"; import { Cors } from "aws-cdk-lib/aws-apigateway"; import { AccountPrincipal, AnyPrincipal, Effect, PolicyDocument, PolicyStatement, } from "aws-cdk-lib/aws-iam"; import { Construct } from "constructs"; import { Api, CalculateFunction } from "calculateapi-typescript-infra"; /** * Api construct props. */ export interface CalculateApiProps { /** * Instance of the UserIdentity. */ readonly userIdentity: UserIdentity; } /** * Infrastructure construct to deploy a Type Safe API. */ export class CalculateApi extends Construct { /** * API instance */ public readonly api: Api; constructor(scope: Construct, id: string, props?: CalculateApiProps) { super(scope, id); this.api = new Api(this, id, { defaultAuthorizer: Authorizers.iam(), corsOptions: { allowOrigins: Cors.ALL_ORIGINS, allowMethods: Cors.ALL_METHODS, }, integrations: { calculate: { integration: Integrations.lambda(new CalculateFunction(this, "CalculateFunction")) } }, policy: new PolicyDocument({ statements: [ // Here we grant any AWS credentials from the account that the prototype is deployed in to call the api. // Machine to machine fine-grained access can be defined here using more specific principals (eg roles or // users) and resources (ie which api paths may be invoked by which principal) if required. // If doing so, the cognito identity pool authenticated role must still be granted access for cognito users to // still be granted access to the API. new PolicyStatement({ effect: Effect.ALLOW, principals: [new AccountPrincipal(Stack.of(this).account)], actions: ["execute-api:Invoke"], resources: ["execute-api:/*"], }), // Open up OPTIONS to allow browsers to make unauthenticated preflight requests new PolicyStatement({ effect: Effect.ALLOW, principals: [new AnyPrincipal()], actions: ["execute-api:Invoke"], resources: ["execute-api:/*/OPTIONS/*"], }), ], }), }); // Grant authenticated users access to invoke the api props?.userIdentity.identityPool.authenticatedRole.addToPrincipalPolicy( new PolicyStatement({ effect: Effect.ALLOW, actions: ["execute-api:Invoke"], resources: [this.api.api.arnForExecuteApi("*", "/*", "*")], }), ); } }
  9. 通过运行以下命令来生成更改:

    npx projen build

项目完成构建后,您可以查看更新的生成的逻辑示意图,该图可在中找到/packages/infra/main/cdk.out/cdkgraph/diagram.png。该图显示了如何添加函数并将其连接到API创建的函数。修改CDK代码后,此图也会更新。

现在,您可以通过将更改推送并合并到仓库的主分支来部署更改。

第 5 步:推送和合并代码更改

提交并推送您的代码更改,然后可以将其合并到源存储库的主分支中。

将更改推送到您的功能分支

  • 通过运行以下命令提交更改并将其推送到您的功能分支:

    git add .
    git commit -m "my commit message"
    git push

推送更改会触发功能分支的新工作流程运行,您可以在 CodeCatalyst 控制台中查看该工作流程。然后,您可以创建一个拉取请求,将更改合并到源存储库的主分支中。将功能分支合并到主分支会触发发布工作流程。您也可以将拉取请求链接到您的问题。

创建拉取请求并将其链接到您的议题

  1. 在你的 monorepo 项目中,执行以下任一操作:

    • 在导航窗格中,选择代码,选择拉取请求,然后选择创建拉取请求

    • 在存储库主页上,选择 “更多”,然后选择 “创建拉取请求”。

    • 在项目页面上,选择创建拉取请求

  2. 源代码库中,确保指定的源存储库是包含已提交代码的存储库。只有当你没有从仓库的主页创建拉取请求时,此选项才会出现。

  3. 在 D est ination 分支中,在查看代码后,选择要将代码合并到的主分支。

  4. 源分支中,选择包含已提交代码的功能分支。

  5. Pull req uest 标题中,输入一个标题,以帮助其他用户了解需要审阅的内容及其原因。

  6. (可选)在拉取请求描述中,提供诸如问题链接或更改描述之类的信息。

    提示

    你可以选择 “为我写描述”, CodeCatalyst 自动生成拉取请求中包含的更改的描述。将自动生成的描述添加到拉取请求后,您可以对其进行更改。

    此功能要求为该空间启用生成式 AI 功能。有关更多信息,请参阅在 A mazon 中管理生成式 AI 功能 CodeCatalyst

  7. 在 “问题” 中,选择 “关联问题”,然后选择您在中创建的议题第 2 步:创建议题以进行协作和跟踪工作。要取消议题的链接,请选择取消链接图标。

  8. (可选)在必填审稿人中,选择添加所需的审阅者。从项目成员列表中进行选择以添加他们。在将拉取请求合并到目标分支之前,必需的审阅者必须批准更改。

    注意

    您不能将审阅者同时添加为必填审阅者和可选审阅者。您无法将自己添加为审阅者。

  9. (可选)在可选审阅者中,选择添加可选审阅者。从项目成员列表中进行选择以添加他们。在将拉取请求合并到目标分支之前,可选的审阅者不必将更改作为一项要求进行批准。

  10. 您的拉取请求必须由审阅者或您自己审阅并合并到主分支中。有关更多信息,请参阅 合并拉取请求

    当您的更改合并到源存储库的主分支时,会自动触发新的工作流程。

  11. 合并完成后,您可以将问题移至 “完成”。

    1. 在导航窗格中,选择 “问题”。

    2. 选择在中创建的问题第 2 步:创建议题以进行协作和跟踪工作,选择 “状态” 下拉列表,然后选择 “完成”。

发布工作流程将在成功运行后部署您的应用程序,因此您可以查看更改。

确认发布工作流程并查看您的网站

  1. 在 monorepo 项目的导航窗格中,选择 C I/CD,然后选择工作流程。

  2. 对于发布工作流程,请选择最新运行的工作流程以查看详细信息。有关更多信息,请参阅 查看单次运行的状态和详细信息

  3. 成功完成工作流程运行后,选择工作流程中的最后一个操作(Deplo y-B-eta-ap-souteast 2),然后选择变量。

  4. 通过复制并粘贴来自的链接来查看已部署的网站 MyPDKApiwebsiteDistributionDomain将XXXXX行命名到新的浏览器窗口中。

  5. 输入您在中创建的用户名和密码第 6 步:确认发布工作流程并查看您的网站,然后选择登录

  6. (可选)测试应用程序中的更改。

    1. 选择POST下拉菜单。

    2. numberA和输入两个值number B,然后选择执行

    3. 响应正文中确认结果。

随着时间的推移,PDK蓝图的目录版本可能会发生变化。您可以将项目的蓝图更改为目录版本,以了解最新的更改。在更改项目的蓝图版本之前,您可以查看代码更改和受影响的环境。有关更多信息,请参阅 更改项目中的蓝图版本