提交你的第一个示例Serverless Examples 社区贡献指南与 examples.json 机制详解【免费下载链接】examplesServerless Examples – A collection of boilerplates and examples of serverless architectures built with the Serverless Framework on AWS Lambda, Microsoft Azure, Google Cloud Functions, and more.项目地址: https://gitcode.com/gh_mirrors/exa/examplesServerless Examples 是基于 Serverless Framework 构建的即开即用示例库覆盖 Node.js、Python、Golang、Ruby、Java、Rust、.NET 等多种运行时。本文带你读懂驱动整个仓库的 examples.json 机制并手把手走完提交第一个 serverless 示例的 5 个步骤零门槛即可上手社区贡献。什么是 Serverless Examples可一键部署的无服务器示例库Serverless Examples 收集了一批可直接部署的 Serverless Framework 服务每一个独立目录就是一个完整示例包含serverless.yml部署配置和一份讲解用法与用例的README.md。这个仓库有几个对新手特别友好的特点目录扁平清晰一个目录一个示例如 aws-node-simple-http-endpoint/ 用最轻的方式返回当前时间非常适合第一个示例多语言覆盖从 Node.js、Python 到 Golang、Ruby、Java、Rust、.NET总有一款是你的主力语言首页表格自动生成几百个示例的导航表格不需要人工维护背后机制下文详解。一个典型的示例部署后会在云上形成一条完整的 serverless 链路。下图是仓库中一个 Ruby 示例的架构请求经 API Gateway 进入由 Lambda 生产者写入 SQS再由 Lambda 工作消费者落库到 DynamoDB全程无需管理任何服务器。示例长什么样标准目录结构与 frontmatter 结构一个合格的示例主要由两类文件构成文件作用serverless.yml部署配置函数、事件、资源DynamoDB、SQS 等都在这里声明README.md使用说明且文件开头必须带 frontmatter HTML 注释frontmatter 就是写在 README 最顶部的一段 HTML 注释例如 aws-node-simple-http-endpoint/README.md 开头!-- title: My First Serverless Example description: A minimal HTTP endpoint deployed with the Serverless Framework framework: v4 platform: aws language: nodeJS authorLink: 你的主页链接 authorName: 你的名字 authorAvatar: 你的头像图片链接 --其中title、description、framework、platform、language、authorLink、authorName、authorAvatar共8 个必填键一个都不能少。除了简单接口仓库里也有 Step Functions 状态机、沙箱微虚拟机、MCP 服务器等更复杂的形态比如 aws-ruby-step-functions/ 中的周末出行状态机部署后在控制台中能看到完整的执行路径examples.json 机制详解一份 JSON 驱动整个仓库的 README首页 README.md 中数百行示例表格并非手写唯一数据源是根目录的 examples.json。整个机制可以画成一条单向数据流examples.json ──► generate-readme.js ──► README.md 中的两张自动表格关键细节如下每个示例对应一个 JSON 对象核心字段一览字段含义说明title展示标题不能是TODOname目录名与示例目录名一致description一句话简介会拼进表格单元格githubUrl示例目录链接一方示例指向本仓库对应目录framework框架版本目前固定为v4language运行时语言node / python / go / ruby / java / rust / csharp 等platform云平台大多为awscommunity是否社区示例可选true表示托管在社区自己的仓库脚本定位标记位替换内容generate-readme.js 找到 README 中AUTO-GENERATED-CONTENT起止标记把标记之间的表格整体替换为最新数据分一方示例表和社区示例表两张CI 有一致性闸门package.json 中的check-docs脚本会重新生成文档并比对README.md与examples.json是否有差异所以提交 PR 时必须带上重新生成的 README运行时标签会做归一化脚本内置映射表如node、typescript归一为nodeJS所以你填node或nodejs都能正确显示。提交你的第一个 serverless 示例5 步走通前置准备将仓库 fork 到你自己的账号并新建分支本地需要 Node.js ≥ 24见 package.json 的engines声明。第 1 步创建示例目录按仓库惯例命名目录如aws-node-xxx或aws-python-xxx放入serverless.yml和你的函数代码。多服务示例只需保证最浅层目录包含serverless.yml即可校验脚本会从这里识别示例根见 validate.js。第 2 步编写带 frontmatter 的 README.md按上一节模板在 README 开头写 frontmatter 注释正文介绍用例、本地调试与部署方式。⚠️ 注意值里如果包含: 务必加引号否则会在文档站端的 YAML 解析中被清空。第 3 步在 examples.json 中新增条目在 examples.json 数组中按字母序插入你的条目形如{ title: My First Serverless Example, name: aws-node-my-first-example, description: A minimal HTTP endpoint deployed with the Serverless Framework, githubUrl: 本仓库中该示例目录的链接, framework: v4, language: node, platform: aws }第 4 步本地校验并重新生成文档npm run validate npm run docs两条命令都必须通过validate检查所有示例的 frontmatter 合法性docs重新生成 README 表格。npm run validate通过时会输出all example READMEs valid。第 5 步确认 serverless package 成功后提交 PR在示例目录内运行serverless package确保打包成功然后把示例目录、examples.json 改动、重新生成的 README.md一起提交 PR。 你的示例生效后在云上看到的结果应该类似这样——定时示例自动往 DynamoDB 写入了一条条带时间戳的记录常见贡献坑点npm run validate 的 4 条校验规则validate.js 会递归扫描所有示例目录以下坑点出现频率最高README.md 缺失或没有 frontmatter HTML 注释—— 注释格式必须是!-- key: value --每行一个键值对8 个必填字段缺一不可—— 最常见漏项是authorAvatarframework 必须恰好是v4—— 写成v3或留空都会被拦下含: 的值未加引号—— 例如描述里写了冒号加空格记得用单引号包起来。另外title为TODO的占位值也不允许提交前请把标题写好。提交社区示例community: true 的第二条入口如果示例代码托管在你自己的独立仓库里走社区示例通道更轻量在 examples.json 中新增条目加上community: true并把githubUrl指向你的仓库运行npm run docs重新生成 README连同 README 一起提交 PR。社区示例会出现在首页下方的 Community Examples 表格中无需维护示例代码本身。提交前检查清单PR 发出前确认这 5 项示例目录内serverless package执行成功npm run validate无任何报错npm run docs重新生成的README.md已包含在 PR 中frontmatter 8 个必填字段齐全含冒号的值已加引号示例设计符合 AWS Lambda 的资源限制内存、超时、部署包大小等例如部署包压缩后 50 MB 上限全部勾选后放心提交 PR 吧。合并之后你的示例就会出现在 Serverless Examples 首页的示例表格中成为下一位新手git clone之后就能一键部署的起点。⚡️【免费下载链接】examplesServerless Examples – A collection of boilerplates and examples of serverless architectures built with the Serverless Framework on AWS Lambda, Microsoft Azure, Google Cloud Functions, and more.项目地址: https://gitcode.com/gh_mirrors/exa/examples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考