拓冰网站定制 
Encore.ts Hello World 实战用不到 10 行 TypeScript 定义生产级 API 端点【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore导读本文以 Encore 开源仓库中的 Hello World 概念文档 为骨架结合仓库内encore.dev/api的运行时源码与 e2e 测试样例带你从零掌握 Encore.ts 的核心编程模型用声明式方式将普通 TypeScript async 函数包装成类型安全、自带请求解析与校验的 API 端点。读完本文你将能够写出自己的第一个 Encore.ts 服务、理解api函数各个选项的实际语义并完成本地运行、调用与调试的全流程。一切从api函数开始Encore.ts 的核心理念非常直接API 端点就是普通的 TypeScript async 函数唯一不同的是它被encore.dev/api模块导出的api函数包装了一下。这一包装告诉 Encore这个函数是一个 API 端点请求数据作为函数入参传入函数返回值作为响应数据返回。整个定义过程是完全声明式的。Encore 在编译期解析你的源码自动生成所需的样板代码boilerplate包括 HTTP 路由注册、请求解析、类型校验与错误处理——全程零手工样板代码。在 runtime 源码 中可以看到api的真实签名它是一个泛型函数约束入参Params和响应Response均为对象类型或void并原样返回处理函数export function api Params extends object | void void, Response extends object | void void ( options: APIOptions, fn: (params: Params) PromiseResponse ): HandlerFnParams, Response;也就是说运行时层面的api只是一个标记函数真正的路由、序列化、校验逻辑由 Encore 编译器在编译期根据APIOptions与函数签名生成。这也是声明式开发体验的底层来源。不到 10 行的 Hello WorldHello World 文档 给出了一个完整可运行的最小示例——定义一个接收 URL 路径参数、返回 JSON 响应的公开 GET 端点代码不足 10 行import { api } from encore.dev/api; export const get api( { expose: true, method: GET, path: /hello/:name }, async ({ name }: { name: string }): PromiseResponse { const msg Hello ${name}!; return { message: msg }; } ); interface Response { message: string; }逐行拆解这段代码你能看到 Encore.ts 的所有关键机制{ expose: true }把端点暴露到公网。如果不设置端点默认仅在应用内部网络可达详情见下文 APIOptions 说明。method: GET与path: /hello/:name声明 HTTP 方法与路由。:name是路径参数占位符Encore 会自动从 URL 中解析它并与函数入参中同名的name字段进行类型匹配。async ({ name }: { name: string })函数入参类型即请求 schema。Encore 根据这一 TypeScript 类型自动完成请求数据的解析与校验——如果请求与 schema 不匹配Encore 会在进入函数体之前直接返回错误。PromiseResponse与interface Response返回值类型即响应 schemaEncore 会自动将返回对象序列化为 JSON 响应。export const get端点通过命名导出的常量暴露给 Encore 编译器识别get同时作为端点的编程名称。同样的 Hello World 模式也出现在仓库的 e2e 测试样例中。例如 e2e-tests/testdata/tsapp/service1/api.ts 里就定义了一个结构几乎完全一致的端点export const hello api( { expose: true, method: GET, path: /hello/:name }, async ({ name }: { name: string }): Promise{ message: string } { return { message: Hello ${name} }; } );这说明 Hello World 并非玩具示例而是 Encore.ts 端到端测试真实覆盖的标准用法。服务Service端点所属的边界上面定义的端点归属于哪个服务答案在同一个目录下的encore.service.ts文件中。Encore.ts 规定一个目录及其所有子目录构成一个服务服务通过encore.service.ts文件声明import { Service } from encore.dev/service; export default new Service(hello);Service 类实现 揭示了其设计意图构造参数name是服务名Service必须从名为encore.service.ts的文件中被调用以便 Encore 高效识别可能存在的服务定义。e2e 测试仓库中的 tsapp 就是多服务结构的直接范例service1/与service2/各自拥有自己的encore.service.ts、api.ts和单元测试文件api.test.ts服务之间通过 Encore 自动生成的客户端代码~encore/clients进行服务间调用。想要新增服务只需创建一个新目录放入导出新Service的encore.service.ts即可。api函数选项详解APIOptions 全字段api的第一个参数是配置对象。根据 runtime 源码中的 APIOptions 定义它支持以下字段理解它们能帮你写出更精确的端点字段类型默认值含义methodMethod \| Method[] \| *必填端点匹配的 HTTP 方法可传数组匹配多个方法传*匹配任意方法pathstring/service-name.endpoint-name请求路径。:name匹配单个路径段*name匹配任意数量的段exposebooleanfalse是否将端点公开到互联网false时仅应用内部网络服务间调用、Cron 任务可达authbooleanfalse是否必须携带有效认证凭据为true且未认证时 Encore 返回401 UnauthorizedbodyLimitnumber \| null2MiB请求体最大字节数超限则终止处理并返回错误设为null表示不限制tagsstring[]无端点的标签用于客户端生成时过滤端点和中间件定向sensitivebooleanfalse为true时请求/响应负载与 HTTP 头将从 trace 中排除保护敏感数据几点值得展开的语义同样有源码注释为依据path缺省时的默认值是/service-name.endpoint-name。也就是说在hello服务中定义一个名为world的端点不写path时路由自动为/hello.world。示例中的path: /hello/:name只是更符合直觉的显式写法。expose控制网络边界{ expose: false }是默认值这类私有 API 永远不会被外部访问只能被应用内其他服务或 Cron 任务调用{ expose: true }则对全网开放。这在 Hello World 之外、涉及多服务架构时尤为关键。sensitive: true与可观测性挂钩处理 API Key、密码、PII 等敏感信息时设置该选项可防止敏感数据进入 trace是生产环境的常用防护手段。defining-apis 指南 对上述选项尤其是expose与auth有更完整的场景化论述可作为进阶阅读。请求与响应的四种形态api包装的函数其入参与返回值可以自由组合。Encore 支持四种端点形态同时使用请求与响应数据api({ ... }, async (params: Params): PromiseResponse {});只返回响应api({ ... }, async (): PromiseResponse {});只有请求数据api({ ... }, async (params: Params): Promisevoid {});无请求也无响应api({ ... }, async (): Promisevoid {});由于api是泛型函数同样的四种形态也可以用类型参数表达apiParams, Response、apivoid, Response、apiParams, void、apivoid, void。对于GET、HEAD、DELETE这类不支持请求体的方法请求参数默认从查询字符串解析其他方法默认从 JSON 请求体解析。此外通过Header、Query、Cookie类型还可以按字段粒度控制解析来源这部分内容详见 defining-apis 指南。本地运行、调用与热重载创建项目与运行应用的方式与 quick-start 指南 一致# 交互式创建应用语言选择 TypeScript模板选择 Hello World $ encore app create # 进入应用目录并启动本地开发环境 $ cd your-app-name $ encore runencore run会启动本地开发环境与开发面板默认地址http://localhost:9400并自动搭好应用所需的全部基础设施包括数据库与 Pub/Sub。应用监听于http://localhost:4000用 curl 即可验证端点$ curl http://localhost:4000/hello/world {Message: Hello, world!}当保存代码改动时Encore CLI 守护进程会立刻检测到变更、自动重新编译并热重载应用终端输出大致如下Changes detected, recompiling... Reloaded successfully. TRC registered endpoint endpointWorld path/hello/:name servicehello TRC listening for incoming HTTP requests此时再次调用同一个 URL即可立即看到新逻辑生效。从 Hello World 走向完整后端Hello World 只是 Encore.ts 后端框架的入口。一旦掌握了api的声明式定义方式其余原语的使用方式是同构的在代码中声明式地使用框架自动处理基础设施。相关原语指南如下均为仓库内文档可对照学习Services 服务定义Defining APIs 完整 API 定义指南Databases 数据库Cron Jobs 定时任务Pub/Sub 消息队列Secrets 密钥管理关于部署可以执行encore build docker MY-IMAGE:TAG在宿主机上编译并生成 Docker 镜像也可以git push encore将应用推送到 Encore Cloud 完成云端构建与部署。源码参考与延伸阅读本文涉及的关键证据均可在仓库中直接查验Hello World 概念文档本文的主题来源。encore.dev/api 模块源码api函数签名与APIOptions全字段定义L59-L174。encore.dev/service 模块源码Service类实现与服务声明规则。e2e 测试样例 service1/api.tsHello World 模式在端到端测试中的真实用法以及路径参数、自定义状态码、服务间调用的更多示例。Quick Start 指南从安装、建项目到本地运行、调用的完整演练。【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Encore.ts Hello World 实战：用不到 10 行 TypeScript 定义生产级 API 端点
Encore.ts Hello World 实战用不到 10 行 TypeScript 定义生产级 API 端点【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore导读本文以 Encore 开源仓库中的 Hello World 概念文档 为骨架结合仓库内encore.dev/api的运行时源码与 e2e 测试样例带你从零掌握 Encore.ts 的核心编程模型用声明式方式将普通 TypeScript async 函数包装成类型安全、自带请求解析与校验的 API 端点。读完本文你将能够写出自己的第一个 Encore.ts 服务、理解api函数各个选项的实际语义并完成本地运行、调用与调试的全流程。一切从api函数开始Encore.ts 的核心理念非常直接API 端点就是普通的 TypeScript async 函数唯一不同的是它被encore.dev/api模块导出的api函数包装了一下。这一包装告诉 Encore这个函数是一个 API 端点请求数据作为函数入参传入函数返回值作为响应数据返回。整个定义过程是完全声明式的。Encore 在编译期解析你的源码自动生成所需的样板代码boilerplate包括 HTTP 路由注册、请求解析、类型校验与错误处理——全程零手工样板代码。在 runtime 源码 中可以看到api的真实签名它是一个泛型函数约束入参Params和响应Response均为对象类型或void并原样返回处理函数export function api Params extends object | void void, Response extends object | void void ( options: APIOptions, fn: (params: Params) PromiseResponse ): HandlerFnParams, Response;也就是说运行时层面的api只是一个标记函数真正的路由、序列化、校验逻辑由 Encore 编译器在编译期根据APIOptions与函数签名生成。这也是声明式开发体验的底层来源。不到 10 行的 Hello WorldHello World 文档 给出了一个完整可运行的最小示例——定义一个接收 URL 路径参数、返回 JSON 响应的公开 GET 端点代码不足 10 行import { api } from encore.dev/api; export const get api( { expose: true, method: GET, path: /hello/:name }, async ({ name }: { name: string }): PromiseResponse { const msg Hello ${name}!; return { message: msg }; } ); interface Response { message: string; }逐行拆解这段代码你能看到 Encore.ts 的所有关键机制{ expose: true }把端点暴露到公网。如果不设置端点默认仅在应用内部网络可达详情见下文 APIOptions 说明。method: GET与path: /hello/:name声明 HTTP 方法与路由。:name是路径参数占位符Encore 会自动从 URL 中解析它并与函数入参中同名的name字段进行类型匹配。async ({ name }: { name: string })函数入参类型即请求 schema。Encore 根据这一 TypeScript 类型自动完成请求数据的解析与校验——如果请求与 schema 不匹配Encore 会在进入函数体之前直接返回错误。PromiseResponse与interface Response返回值类型即响应 schemaEncore 会自动将返回对象序列化为 JSON 响应。export const get端点通过命名导出的常量暴露给 Encore 编译器识别get同时作为端点的编程名称。同样的 Hello World 模式也出现在仓库的 e2e 测试样例中。例如 e2e-tests/testdata/tsapp/service1/api.ts 里就定义了一个结构几乎完全一致的端点export const hello api( { expose: true, method: GET, path: /hello/:name }, async ({ name }: { name: string }): Promise{ message: string } { return { message: Hello ${name} }; } );这说明 Hello World 并非玩具示例而是 Encore.ts 端到端测试真实覆盖的标准用法。服务Service端点所属的边界上面定义的端点归属于哪个服务答案在同一个目录下的encore.service.ts文件中。Encore.ts 规定一个目录及其所有子目录构成一个服务服务通过encore.service.ts文件声明import { Service } from encore.dev/service; export default new Service(hello);Service 类实现 揭示了其设计意图构造参数name是服务名Service必须从名为encore.service.ts的文件中被调用以便 Encore 高效识别可能存在的服务定义。e2e 测试仓库中的 tsapp 就是多服务结构的直接范例service1/与service2/各自拥有自己的encore.service.ts、api.ts和单元测试文件api.test.ts服务之间通过 Encore 自动生成的客户端代码~encore/clients进行服务间调用。想要新增服务只需创建一个新目录放入导出新Service的encore.service.ts即可。api函数选项详解APIOptions 全字段api的第一个参数是配置对象。根据 runtime 源码中的 APIOptions 定义它支持以下字段理解它们能帮你写出更精确的端点字段类型默认值含义methodMethod \| Method[] \| *必填端点匹配的 HTTP 方法可传数组匹配多个方法传*匹配任意方法pathstring/service-name.endpoint-name请求路径。:name匹配单个路径段*name匹配任意数量的段exposebooleanfalse是否将端点公开到互联网false时仅应用内部网络服务间调用、Cron 任务可达authbooleanfalse是否必须携带有效认证凭据为true且未认证时 Encore 返回401 UnauthorizedbodyLimitnumber \| null2MiB请求体最大字节数超限则终止处理并返回错误设为null表示不限制tagsstring[]无端点的标签用于客户端生成时过滤端点和中间件定向sensitivebooleanfalse为true时请求/响应负载与 HTTP 头将从 trace 中排除保护敏感数据几点值得展开的语义同样有源码注释为依据path缺省时的默认值是/service-name.endpoint-name。也就是说在hello服务中定义一个名为world的端点不写path时路由自动为/hello.world。示例中的path: /hello/:name只是更符合直觉的显式写法。expose控制网络边界{ expose: false }是默认值这类私有 API 永远不会被外部访问只能被应用内其他服务或 Cron 任务调用{ expose: true }则对全网开放。这在 Hello World 之外、涉及多服务架构时尤为关键。sensitive: true与可观测性挂钩处理 API Key、密码、PII 等敏感信息时设置该选项可防止敏感数据进入 trace是生产环境的常用防护手段。defining-apis 指南 对上述选项尤其是expose与auth有更完整的场景化论述可作为进阶阅读。请求与响应的四种形态api包装的函数其入参与返回值可以自由组合。Encore 支持四种端点形态同时使用请求与响应数据api({ ... }, async (params: Params): PromiseResponse {});只返回响应api({ ... }, async (): PromiseResponse {});只有请求数据api({ ... }, async (params: Params): Promisevoid {});无请求也无响应api({ ... }, async (): Promisevoid {});由于api是泛型函数同样的四种形态也可以用类型参数表达apiParams, Response、apivoid, Response、apiParams, void、apivoid, void。对于GET、HEAD、DELETE这类不支持请求体的方法请求参数默认从查询字符串解析其他方法默认从 JSON 请求体解析。此外通过Header、Query、Cookie类型还可以按字段粒度控制解析来源这部分内容详见 defining-apis 指南。本地运行、调用与热重载创建项目与运行应用的方式与 quick-start 指南 一致# 交互式创建应用语言选择 TypeScript模板选择 Hello World $ encore app create # 进入应用目录并启动本地开发环境 $ cd your-app-name $ encore runencore run会启动本地开发环境与开发面板默认地址http://localhost:9400并自动搭好应用所需的全部基础设施包括数据库与 Pub/Sub。应用监听于http://localhost:4000用 curl 即可验证端点$ curl http://localhost:4000/hello/world {Message: Hello, world!}当保存代码改动时Encore CLI 守护进程会立刻检测到变更、自动重新编译并热重载应用终端输出大致如下Changes detected, recompiling... Reloaded successfully. TRC registered endpoint endpointWorld path/hello/:name servicehello TRC listening for incoming HTTP requests此时再次调用同一个 URL即可立即看到新逻辑生效。从 Hello World 走向完整后端Hello World 只是 Encore.ts 后端框架的入口。一旦掌握了api的声明式定义方式其余原语的使用方式是同构的在代码中声明式地使用框架自动处理基础设施。相关原语指南如下均为仓库内文档可对照学习Services 服务定义Defining APIs 完整 API 定义指南Databases 数据库Cron Jobs 定时任务Pub/Sub 消息队列Secrets 密钥管理关于部署可以执行encore build docker MY-IMAGE:TAG在宿主机上编译并生成 Docker 镜像也可以git push encore将应用推送到 Encore Cloud 完成云端构建与部署。源码参考与延伸阅读本文涉及的关键证据均可在仓库中直接查验Hello World 概念文档本文的主题来源。encore.dev/api 模块源码api函数签名与APIOptions全字段定义L59-L174。encore.dev/service 模块源码Service类实现与服务声明规则。e2e 测试样例 service1/api.tsHello World 模式在端到端测试中的真实用法以及路径参数、自定义状态码、服务间调用的更多示例。Quick Start 指南从安装、建项目到本地运行、调用的完整演练。【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考