企业官网建设流程全解析

• 示例工程
• 教程
• 后端

导读

本文以 AWS 官方文档代码示例仓库（aws-doc-sdk-examples）中 PHP 技术栈元数据规范 为核心，系统讲解为 PHP AWS SDK 示例构建标准项目结构、Composer 配置与元数据文件的方法。读者将掌握{Service}Actions.php、{Service}Service.php、Runner.php、Hello{Service}.php等文件的职责划分与命名约定，理解 PSR-4 自动加载、Apache-2.0 许可头、PHPUnit 测试组织等硬性要求，并能在仓库现有源码（如 S3 示例目录）中找到逐一对应的实现范例。

一、规范的角色定位：从知识库查询到代码生成

这份元数据文档首先是面向代码生成 Agent（如 Bedrock 等调用方）的"先决条件清单"，强调在任何 PHP 示例代码生成之前，必须完成知识库咨询与 AWS 服务调研，其执行顺序如下：

1. 列出可用知识库：调用ListKnowledgeBases()获取当前可用的知识库集合；
2. 查询编码规范：查询coding-standards-KB中的PHP-code-example-standards条目，这是 PHP 代码风格与结构要求的唯一权威来源；
3. 查询实现模式：查询PHP-premium-KB中的PHP implementation patterns metadata，获取经过验证的服务封装与场景实现模式；
4. 调研 AWS 服务：通过search_documentation搜索目标服务的核心 API 操作，并read_documentation读取对应服务开发者指南页面。

文档明确警示：跳过知识库咨询会导致生成错误的代码结构。从仓库实际布局看，php/example_code 下每个服务目录（s3、iam、dynamodb、ec2、glue、lambda、kms、bedrock-runtime 等）都遵循着统一模板，这正是该元数据规范落地后的产物，因此它也是人类开发者编写或评审示例代码时可直接对照的清单。

二、标准文件结构与职责划分

规范要求每个服务示例目录采用扁平化结构，典型布局如下：

example_code/{service}/ ├── Hello{Service}.php # 独立的 hello 场景文件 ├── {Service}Actions.php # 单项操作示例 ├── {Service}Service.php # 服务封装类 ├── Runner.php # 交互式菜单运行器 ├── composer.json # Composer 配置 ├── README.md # 服务文档 └── tests/ ├── {Service}Test.php # 单元与集成测试 └── phpunit.xml # PHPUnit 配置

规范同时要求：根层放置主示例文件与配置，tests/ 目录存放全部测试文件与 PHPUnit 配置，保持目录扁平、不建子目录。仓库中的 S3 示例目录 是这套结构的忠实实现：

• helloS3.php：独立的 hello 场景，仅用几行代码创建S3Client并listBuckets()；
• S3Service.php：服务封装类，集中封装createBucket、emptyAndDeleteBucket等操作；
• GettingStartedWithS3.php：入门场景（对应规范中的{Service}Actions级别的场景文件）；
• Runner.php：标准入口，require "GettingStartedWithS3.php"后实例化并依次调用helloService()、runExample()、cleanUp()；
• tests/：含 S3BasicsTest.php 等测试文件。

三、Composer 配置模式（强制性要求）

规范规定每个服务目录都必须携带 composer.json，模板如下：

{ "name": "awsdocs/{service}-examples", "description": "AWS SDK for PHP examples for {AWS Service}", "type": "library", "license": "Apache-2.0", "authors": [ { "name": "AWS Documentation Team", "email": "aws-doc-sdk-examples@amazon.com" } ], "require": { "php": "^8.1", "aws/aws-sdk-php": "^3.209", "ext-readline": "*" }, "require-dev": { "phpunit/phpunit": "^9.5" }, "autoload": { "psr-4": { "{Service}\\": "./" } }, "autoload-dev": { "psr-4": { "{Service}\\Tests\\": "tests/" } }, "scripts": { "test": "phpunit", "test-unit": "phpunit --group unit", "test-integ": "phpunit --group integ" } }

仓库中 IAM 示例的 composer.json 即为该模板的简化落地版本：require指定aws/aws-sdk-php: ^3.209，require-dev引入phpunit/phpunit: ^9.5，autoload.files直接加载IAMService.php。而 S3 示例的 composer.json 更进一步，通过 PSR-4 将Ec2\、Iam\、S3\、AwsUtilities\命名空间映射到各自目录，并通过files加载 TestableReadline.php —— 这是对规范"交互式示例依赖 readline 扩展"的工程化处理：生产环境使用ext-readline，测试环境则注入可测试的 readline 替身。

3.1 顶层聚合配置

除服务级 composer.json 外，仓库在 php/example_code/composer.json 提供聚合配置，统一声明aws/aws-sdk-php ^3.283.2、guzzlehttp/guzzle ^7.8.0、ext-zip等依赖，并将DynamoDb\、Ec2\、Glue\、Iam\、Kms\、Lambda\、S3\等多个服务命名空间全部映射到各自目录，同时把 aws_utilities 中的工具类纳入自动加载。这说明规范模板与真实仓库是"骨架—实现"关系：模板保证一致性，真实项目可按需扩展命名空间映射。

四、文件命名与代码结构标准

4.1 命名约定

• 类文件与主示例文件使用PascalCase；
• 操作示例统一为{Service}Actions.php（如S3Actions.php）；
• hello 场景统一为Hello{Service}.php（如HelloS3.php，仓库实际命名为 helloS3.php，含义一致）；
• 运行器固定命名为Runner.php；
• 测试文件命名为{Service}Test.php；
• 服务封装类命名为{Service}Service.php。

4.2 代码结构标准

4.3 版权头（强制）

每个 PHP 文件顶部必须包含 Apache-2.0 许可头，且必须位于<?php之后：

<?php // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0

该头在仓库中所有示例文件中均可见，如 S3Service.php、Runner.php 与测试文件 S3BasicsTest.php。注意仓库实际采用//行注释形式，而非/* */块注释。

4.4 命名空间结构模板

服务封装类应遵循以下骨架（AWS SDK 类型导入是标配）：

<?php // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 namespace {Service}; use Aws\{Service}\{Service}Client; use Aws\Exception\AwsException; use Aws\{Service}\Exception\{Service}Exception; class {Service}Service { // Class implementation }

从 S3Service.php 的实际实现看，除规范列出的导入外，还会按需引入Aws\Result、Aws\CommandInterface以及仓库自己的 aws_utilities 工具类（如AWSServiceClass），并在构造函数中按version => latest+region创建客户端，或接受外部注入的客户端以便测试。

五、Composer 依赖硬性要求

规范用清单形式（✅）明确了六条不可妥协的依赖要求：

• ✅必须指定最低 PHP 版本（8.1+）；
• ✅必须指定最低 AWS SDK 版本（^3.209，保障最新特性与安全修复）；
• ✅必须包含ext-readline（交互式示例依赖）；
• ✅必须配置 PSR-4 自动加载；
• ✅必须包含 PHPUnit（^9.5及以上）；
• ✅必须提供便捷测试脚本（test/test-unit/test-integ）。

5.1 版本基线

值得注意的是，仓库中 EC2 示例 已升级到aws/aws-sdk-php ^3.323，顶层 聚合配置 使用^3.283.2，均不低于规范基线，符合"最低版本随仓库演进向上浮动"的预期。

六、项目元数据标准

• 包命名：awsdocs/{service}-examples格式；
• 许可证：统一Apache-2.0；
• 描述：清晰说明示例所演示的能力（如AWS SDK for PHP examples for Amazon S3）；
• 作者：使用AWS Documentation Team+ 官方邮箱aws-doc-sdk-examples@amazon.com；
• 脚本：包含便捷测试脚本（composer test等）。

七、PSR-4 自动加载配置

规范将 autoload 与 autoload-dev 拆分为两部分：主命名空间{Service}\映射到服务目录根（./），测试命名空间{Service}\Tests\映射到tests/：

"autoload": { "psr-4": { "{Service}\\": "./" } }, "autoload-dev": { "psr-4": { "{Service}\\Tests\\": "tests/" } }

仓库中 S3BasicsTest.php 声明namespace S3\tests;，与规范推荐的{Service}\Tests\略有大小写差异，但整体遵循"测试命名空间映射到 tests 目录"的原则。当服务间存在相互依赖时，真实项目会扩展 psr-4 映射，如 S3 的 composer.json 将Ec2\、Iam\、AwsUtilities\一并引入——这佐证了 PSR-4 配置在实际开发中需要按依赖图灵活扩展。

八、元数据验证流程

规范要求生成/编写完成后执行以下验证，确保元数据可用：

• ✅composer.json通过composer validate校验；
• ✅composer dump-autoload能成功生成自动加载映射；
• ✅composer install能正常安装依赖；
• ✅composer test能运行测试；
• ✅ PSR-4 合规性已验证。

这一闭环与仓库的实际工程实践一致：示例既可直接运行（如php GettingStartedWithS3.php，见 GettingStartedWithS3.php 顶部说明），也可作为集成测试执行——S3BasicsTest.php 通过include Runner.php方式驱动整个入门场景，并以"未抛出异常即通过"的方式验证端到端可用性，测试类还通过@group integ注解与规范中test-integ脚本的--group integ筛选机制精确对应。

结语

这份元数据规范为 AWS SDK for PHP 示例确立了从"编码前的知识库调研"到"目录布局、命名、Composer 配置、自动加载、许可头、测试组织、最终校验"的完整生成链路。开发者编写新服务示例时，只需将{Service}占位符替换为目标服务名，即可在 php/example_code 现有范例（s3、iam、dynamodb、ec2、glue、lambda、kms、bedrock-runtime 等）基础上快速落地一套结构一致、可测试、可维护的示例工程。

• 示例工程
• 教程
• 后端