GoFr 框架入门零样板构建可观测的生产级 Go 微服务【免费下载链接】gofrAn opinionated GoLang framework for accelerated microservice development. Built in support for databases and observability.项目地址: https://gitcode.com/GitHub_Trending/go/gofrGoFr 是一个有主见opinionated的 GoGolangWeb 框架核心目标是用最少的样板代码把日志、指标、追踪、数据源客户端、健康检查等生产级微服务基础设施全部内置好让开发者把精力集中在业务 Handler 上。本文以官方文档 docs/page.md 的入门主线为骨架结合 pkg/gofr 下的真实源码讲解 GoFr 的核心特性、设计原则、五分钟上手流程、默认端口与内置端点以及开箱即用的可观测性能力。读完本文你将能独立初始化一个 GoFr 项目、编写 REST Handler、理解其响应信封与健康检查机制并配置日志、指标与分布式追踪。一、GoFr 是什么为微服务而生的有主见Go 框架GoFr 是一个用 Go 编写的 Web 框架帮助开发者构建健壮、可扩展的微服务应用。它在设计上优先提供简单而非复杂的抽象官方文档docs/page.md将其定位为给所有开发者提供友好、熟悉的抽象层同时保持对 Kubernetes 部署和开箱即用可观测性的强关注。从源码结构看GoFr 的核心是 pkg/gofr/gofr.go 中定义的App结构体它是整个应用的总装车间type App struct { // Config 供应用从环境变量或文件读取自定义配置 Config config.Config grpcServer *grpcServer httpServer *httpServer metricServer *metricServer mcpServer *mcpServer cmd *cmd cron *Crontab // container 为内部实现应用通过 Context 访问其中的数据源、日志、指标等 container *container.Container ... }App同时持有 HTTP、gRPC、Metrics、MCP 四类服务器以及容器Container负责管理数据源、日志、指标注册、Cron 调度器和 CLI 命令。这意味着一次gofr.New()调用见 pkg/gofr/factory.go就会完成配置加载、容器初始化、Tracer 初始化、Metrics 服务初始化以及 HTTP/gRPC 服务器的搭建——这正是零样板的底层来源。二、核心特性Key Features官方文档 docs/page.md 列出了六项核心特性下面逐条结合源码展开。2.1 Logging开箱即用的结构化日志GoFr 默认提供完整的日志能力且天然支持分级日志Level-based Logging。日志级别由环境变量LOG_LEVEL控制取值依次为级别语义DEBUG最低优先级最详细的粒度信息仅建议在开发或受控排障场景开启INFO应用运行中的正常业务事件默认级别NOTICE高于INFO低于WARN用于正常但罕见且重要的事件WARN异常但可恢复的运行状态重试、回退、瞬时故障ERROR失败事件日志会路由到stderr便于接入错误追踪工具FATAL最高优先级代表应用无法继续运行的致命错误会立即终止进程仅在启动期使用日志接口定义在 pkg/gofr/logging/logger.go提供Debug/Info/Notice/Warn/Error/Fatal及对应的f格式化变体。其实现有两个值得注意的性能设计Early Exit 优化logf在进入格式化与分配之前先用原子加载的level判断是否达到配置级别未达到直接返回见 logger.go终端输出加锁pretty print 通过容量为 1 的 channel 充当互斥锁避免多 goroutine 并发写终端导致日志行错位见 logger.go。在终端下日志以彩色 pretty print 展示当输出重定向到文件时每行日志会编码为包含level、time、message、trace_id、gofrVersion字段的 JSON见 logEntry 定义可以直接推送给 Loki、Elasticsearch 等日志系统。日志级别还支持运行期动态调整ChangeLevel方法配合REMOTE_LOG_URL与REMOTE_LOG_FETCH_INTERVAL默认 15 秒即可在不重启服务的前提下远程调整日志级别详见 docs/references/configs/page.md 与 docs/quick-start/observability/page.md。2.2 多样化的响应类型JSON、FILE 等GoFr 的 Handler 统一返回(any, error)响应编码由框架统一处理。默认情况下返回体是一个 JSON 信封见 pkg/gofr/http/responder.go 的编码逻辑{data: ..., error: null}当error非空时则输出{error: {...}}。除此之外框架还支持XML、File、Template、Stream等特殊响应类型它们在 responder.go 的handleSpecialResponseTypes中绕过 JSON 编码、直接以对应 Content-Type 输出。例如文件响应类型定义在 pkg/gofr/http/response/file.gotype File struct { Content []byte ContentType string }开发者只需让 Handler 返回response.File{...}即可下发文件内容如 HTML、图片、二进制流。同时 pkg/gofr/http/response/response.go 提供的Response结构支持携带Metadata与自定义Headers其中SetCustomHeaders会把自定义响应头写入http.ResponseWriter用于设置缓存策略、CORS 头等场景。2.3 Health Check 与 Readiness 监控GoFr 在 HTTP 服务器启动时会自动注册健康检查端点见 pkg/gofr/gofr.go 的httpServerSetup/.well-known/alive存活探针liveness返回200 OK可用于 K8s livenessProbe/.well-known/health就绪探针readiness返回应用名与聚合健康状态可用于 K8s readinessProbe。健康检查的响应体实现在 pkg/gofr/health.gohealthResponse只携带name与聚合status两个字段刻意不暴露任何数据源主机、端口、凭据或连接统计等敏感细节。聚合状态取值包括UP全部依赖健康、DEGRADED至少一个依赖不可用、DOWN默认 fail-closed 兜底值。也就是说一个服务只要用gofr.New()启动就天然具备 K8s 健康探针能力无需额外编码。2.4 MetricsPrometheus 格式的指标暴露GoFr 默认在2121 端口的/metrics端点以 Prometheus 文本格式暴露指标用于监控与分析。默认指标覆盖 HTTP 响应耗时、SQL/Redis 耗时、Go 运行时GC 次数、goroutine 数、内存分配、Pub/Sub 计数、重试与熔断状态、GraphQL 操作统计、Cron 任务执行统计等其中常用项包括指标名类型说明app_http_responsehistogramHTTP 请求响应时间秒app_sql_statshistogramSQL 查询响应时间毫秒app_redis_statshistogramRedis 命令响应时间微秒app_go_routinesgauge运行中的 goroutine 数量app_http_circuit_breaker_stategauge熔断器状态0Closed1Openapp_cron_job_total/app_cron_job_successcounterCron 任务执行总数与成功数完整的默认指标清单见 docs/quick-start/observability/page.md。在本地运行时可访问http://localhost:2121/metrics查看原始指标。若要完全禁用 Metrics 服务设置METRICS_PORT0即可对应 pkg/gofr/factory.go 的initMetricsServer实现还可以通过METRICS_CARDINALITY_LIMIT默认 2000限制单指标标签集数量超出部分折叠进otel.metric.overflow序列防止指标基数爆炸。这些指标可直接被 Prometheus 抓取并在 Grafana 中可视化。2.5 Tracing带可追踪 Span 的请求链路GoFr 基于 OpenTelemetry 自动为所有请求与响应导出追踪数据无需额外埋点。每个进入应用的请求会自动生成X-Correlation-ID并写入响应头随后传播到所有下游请求从而可以在分布式系统中用 correlation ID 串起完整调用链。GoFr 的追踪还自动跨越 Pub/Sub 边界Publish时把活动 trace 上下文注入消息头Subscribe时取出作为子 Span使HTTP → publish → subscribe呈现为一条连贯的 trace。追踪导出器通过TRACE_EXPORTER配置支持四种TRACE_EXPORTER说明otlpOpenTelemetry 协议推荐兼容 Jaeger 1.35、Tempo、Honeycomb、OpenTelemetry Collector 等jaeger直连 Jaeger需配置TRACER_URLzipkin旧式 Zipkin官方标注已弃用建议迁移到 OTLPgofrGoFr 自研的 trace 导出器与收集器服务配套的采样配置为TRACER_RATIO取值 0~1默认 1 即全量导出生产建议下调如0.05自定义认证头用TRACER_HEADERS逗号分隔的keyvalue遵循 OpenTelemetry 标准格式。一个完整的 OTLP 配置示例APP_NAMEtest-service HTTP_PORT8000 # tracing configs TRACE_EXPORTERotlp TRACER_URLlocalhost:4317 TRACER_RATIO1.0 LOG_LEVELDEBUG2.6 分级日志的远程动态调整分级日志能力不仅限于启动时静态设置框架内置了远程日志级别变更支持通过REMOTE_LOG_URL指定日志级别下发服务REMOTE_LOG_FETCH_INTERVAL默认 15 秒控制轮询间隔实现生产环境不重启、动态调级的排障体验详见 docs/references/configs/page.md。三、设计原则Principles官方文档 docs/page.md 给出了六条设计原则结合源码可以逐条找到对应的落地方式Promote simple and clean code提倡简单干净的代码Handler 统一为func(ctx *gofr.Context) (any, error)函数签名注册路由只需一行app.GET(/path, handler)见 pkg/gofr/rest.go。Favor compile-time checked code over dynamic code倾向编译期检查而非动态代码Handler 返回值(any, error)、配置读取、路由注册均在编译期做类型约束而不是靠反射/字符串拼接动态生成。Create a solid foundation for the integration of application modules为应用模块集成打牢基础Container统一承载 SQL、Redis、Pub/Sub、HTTP Service、LLM 等模块Handler 通过ctx直接访问模块间解耦见 pkg/gofr/container/container.go。Encourage a more functional way of programming鼓励函数式编程风格Handler 即纯函数式入口——输入Context、输出(data, error)状态与副作用由框架托管天然易于测试可参考 examples/http-server/main.go 中多个 Handler 的写法。Avoid code duplication避免代码重复健康检查、指标、日志、响应信封等横切逻辑全部收敛到框架内部业务代码不重复实现。Log and store data for analysis purposes为分析记录和存储数据日志默认携带trace_id、gofrVersion等结构化字段并支持 JSON 输出配合指标与追踪构成完整可分析数据面。四、五分钟快速上手从零到第一个 REST 服务4.1 前置条件已安装 Go 工具链仓库 README.md 标注要求Go 1.24 及以上快速入门文档 则标注 Go 1.25请以你拉取代码时go.mod声明的版本为准对 Go 基础语法有一定了解。4.2 初始化模块并安装依赖go mod init github.com/example go get gofr.dev4.3 编写第一个服务将以下代码写入main.gopackage main import gofr.dev/pkg/gofr func main() { // 初始化 gofr 对象加载配置、日志、指标、数据源等 app : gofr.New() // 注册 GET /greet 路由 app.GET(/greet, func(ctx *gofr.Context) (any, error) { return Hello World!, nil }) // 启动服务默认监听 8000 端口可通过配置覆盖 app.Run() }4.4 同步依赖并运行go mod tidy go run main.go浏览器访问http://localhost:8000/greet会看到符合 REST 标准的200响应{data:Hello World!}4.5 理解示例的三步gofr.New()初始化框架完成日志、指标、数据源、Tracer、HTTP/gRPC 服务器的装配是所有 GoFr 服务的标准起点见 pkg/gofr/factory.go注册 Handlerapp.GET(/greet, HandlerFunction)把GET /greet映射到处理函数同理可用app.POST(/todo, ...)、app.PUT、app.DELETE、app.PATCH映射其他方法见 pkg/gofr/rest.go。Handler 签名约定为func(ctx *gofr.Context) (any, error)返回响应数据与错误无错误时返回nil。ctx *gofr.Context是对请求、响应与依赖的包装提供参数解析、数据源访问、日志、Span 创建等能力详见 docs/references/context/page.mdapp.Run()配置并启动 HTTP 服务器、中间件、健康检查端点、Metrics 服务等默认监听 8000 端口。五、默认端口与内置端点app.Run()默认会打开两个监听端口使用 gRPC 时增加第三个若端口被占用服务将无法启动可通过configs/.env中的环境变量覆盖默认端口常量定义在 pkg/gofr/default.go服务默认端口覆盖环境变量暴露端点HTTP8000HTTP_PORT业务路由以及/.well-known/health、/.well-known/alive、/.well-known/swagger、/favicon.ico启用 GraphQL 时还有/.well-known/graphql/uiMetricsPrometheus2121METRICS_PORT设为0可禁用/metrics供 Prometheus / kube-prometheus-stack 抓取gRPC9000GRPC_PORT注册的 gRPC 服务仅在调用RegisterService后开启因此一个全新的app : gofr.New(); app.Run()即可访问http://localhost:8000/your-routes业务接口http://localhost:8000/.well-known/alive存活探针K8s liveness 用http://localhost:8000/.well-known/health聚合健康状态 JSONK8s readiness 用http://localhost:2121/metricsPrometheus 指标。所有/.well-known/*路径默认豁免认证健康探针无需携带凭据。全部可配置环境变量见 docs/references/configs/page.md。六、更多开箱即用的生产级能力除了入门文档强调的特性pkg/gofr/gofr.go 中的App还暴露了丰富的扩展点均与入门文档为生产微服务而生的定位一脉相承零样板 REST CRUDapp.AddRESTHandlers(YourStruct{})基于结构体扫描自动注册 CRUD 路由见 pkg/gofr/rest.go数据源接入通过.env配置即自动连接 SQL、Redis、MongoDB、Cassandra、ClickHouse、Pub/Sub 等数据源详见 docs/datasources/getting-started/page.md数据库迁移app.Migrate(migrationsMap)一键执行版本化迁移见 pkg/gofr/gofr.go外部 HTTP 服务调用app.AddHTTPService(name, url)注册带熔断、重试、连接池能力的 HTTP Service参考 examples/http-server/main.goCron 定时任务app.AddCronJob(schedule, name, fn)支持 5/6 段 cron 表达式见 pkg/gofr/gofr.goPub/Sub 订阅app.Subscribe(topic, handler)注册订阅处理函数启动时并发拉起所有订阅者见 pkg/gofr/gofr.go 与 startSubscriptionsgRPC、GraphQL、WebSocket、MCP、LLM分别对应 pkg/gofr/grpc.go、pkg/gofr/graphql.go、pkg/gofr/websocket.go、pkg/gofr/mcp.go、pkg/gofr/ai/llm启动钩子与优雅关闭app.OnStart(func(ctx) error)在服务接收请求前完成初始化如建连、注册app.Shutdown(ctx)按顺序关闭 HTTP/gRPC/Metrics/MCP 服务器并释放数据源连接见 pkg/gofr/gofr.go静态文件服务app.AddStaticFiles(endpoint, filePath)一行注册静态资源目录见 pkg/gofr/gofr.go。仓库 examples 目录提供了 HTTP 服务、Redis、MySQL、gRPC、WebSocket、GraphQL、Cron、文件存储、AI 等大量可直接运行的完整示例是快速上手各模块的最佳参考。七、总结与后续学习路径本文围绕 docs/page.md 完整梳理了 GoFr 的定位、六大核心特性、六条设计原则并给出了可立即运行的快速上手流程。核心要点可概括为一个有主见的框架gofr.New()一行完成装配健康检查、指标、日志、追踪开箱即用零样板 RESTHandler 签名func(ctx *gofr.Context) (any, error) 统一 JSON 信封天然符合 REST 标准生产就绪默认端口与内置端点直接对接 K8s 探针与 PrometheusOTLP/Jaeger 追踪一键开启。继续深入学习建议按以下顺序阅读仓库文档快速入门第一个 GoFr REST API配置参考全部环境变量与默认值可观测性日志、指标与追踪连接 MySQL 与 连接 Redis进阶指南中间件、gRPC、GraphQL、Pub/Sub 等 系列文档examples 目录 中的可运行示例源码与对应测试。【免费下载链接】gofrAn opinionated GoLang framework for accelerated microservice development. Built in support for databases and observability.项目地址: https://gitcode.com/GitHub_Trending/go/gofr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 19:07:40 · 阅读 1.2k GoFr 框架入门：零样板构建可观测的生产级 Go 微服务
GoFr 框架入门零样板构建可观测的生产级 Go 微服务【免费下载链接】gofrAn opinionated GoLang framework for accelerated microservice development. Built in support for databases and observability.项目地址: https://gitcode.com/GitHub_Trending/go/gofrGoFr 是一个有主见opinionated的 GoGolangWeb 框架核心目标是用最少的样板代码把日志、指标、追踪、数据源客户端、健康检查等生产级微服务基础设施全部内置好让开发者把精力集中在业务 Handler 上。本文以官方文档 docs/page.md 的入门主线为骨架结合 pkg/gofr 下的真实源码讲解 GoFr 的核心特性、设计原则、五分钟上手流程、默认端口与内置端点以及开箱即用的可观测性能力。读完本文你将能独立初始化一个 GoFr 项目、编写 REST Handler、理解其响应信封与健康检查机制并配置日志、指标与分布式追踪。一、GoFr 是什么为微服务而生的有主见Go 框架GoFr 是一个用 Go 编写的 Web 框架帮助开发者构建健壮、可扩展的微服务应用。它在设计上优先提供简单而非复杂的抽象官方文档docs/page.md将其定位为给所有开发者提供友好、熟悉的抽象层同时保持对 Kubernetes 部署和开箱即用可观测性的强关注。从源码结构看GoFr 的核心是 pkg/gofr/gofr.go 中定义的App结构体它是整个应用的总装车间type App struct { // Config 供应用从环境变量或文件读取自定义配置 Config config.Config grpcServer *grpcServer httpServer *httpServer metricServer *metricServer mcpServer *mcpServer cmd *cmd cron *Crontab // container 为内部实现应用通过 Context 访问其中的数据源、日志、指标等 container *container.Container ... }App同时持有 HTTP、gRPC、Metrics、MCP 四类服务器以及容器Container负责管理数据源、日志、指标注册、Cron 调度器和 CLI 命令。这意味着一次gofr.New()调用见 pkg/gofr/factory.go就会完成配置加载、容器初始化、Tracer 初始化、Metrics 服务初始化以及 HTTP/gRPC 服务器的搭建——这正是零样板的底层来源。二、核心特性Key Features官方文档 docs/page.md 列出了六项核心特性下面逐条结合源码展开。2.1 Logging开箱即用的结构化日志GoFr 默认提供完整的日志能力且天然支持分级日志Level-based Logging。日志级别由环境变量LOG_LEVEL控制取值依次为级别语义DEBUG最低优先级最详细的粒度信息仅建议在开发或受控排障场景开启INFO应用运行中的正常业务事件默认级别NOTICE高于INFO低于WARN用于正常但罕见且重要的事件WARN异常但可恢复的运行状态重试、回退、瞬时故障ERROR失败事件日志会路由到stderr便于接入错误追踪工具FATAL最高优先级代表应用无法继续运行的致命错误会立即终止进程仅在启动期使用日志接口定义在 pkg/gofr/logging/logger.go提供Debug/Info/Notice/Warn/Error/Fatal及对应的f格式化变体。其实现有两个值得注意的性能设计Early Exit 优化logf在进入格式化与分配之前先用原子加载的level判断是否达到配置级别未达到直接返回见 logger.go终端输出加锁pretty print 通过容量为 1 的 channel 充当互斥锁避免多 goroutine 并发写终端导致日志行错位见 logger.go。在终端下日志以彩色 pretty print 展示当输出重定向到文件时每行日志会编码为包含level、time、message、trace_id、gofrVersion字段的 JSON见 logEntry 定义可以直接推送给 Loki、Elasticsearch 等日志系统。日志级别还支持运行期动态调整ChangeLevel方法配合REMOTE_LOG_URL与REMOTE_LOG_FETCH_INTERVAL默认 15 秒即可在不重启服务的前提下远程调整日志级别详见 docs/references/configs/page.md 与 docs/quick-start/observability/page.md。2.2 多样化的响应类型JSON、FILE 等GoFr 的 Handler 统一返回(any, error)响应编码由框架统一处理。默认情况下返回体是一个 JSON 信封见 pkg/gofr/http/responder.go 的编码逻辑{data: ..., error: null}当error非空时则输出{error: {...}}。除此之外框架还支持XML、File、Template、Stream等特殊响应类型它们在 responder.go 的handleSpecialResponseTypes中绕过 JSON 编码、直接以对应 Content-Type 输出。例如文件响应类型定义在 pkg/gofr/http/response/file.gotype File struct { Content []byte ContentType string }开发者只需让 Handler 返回response.File{...}即可下发文件内容如 HTML、图片、二进制流。同时 pkg/gofr/http/response/response.go 提供的Response结构支持携带Metadata与自定义Headers其中SetCustomHeaders会把自定义响应头写入http.ResponseWriter用于设置缓存策略、CORS 头等场景。2.3 Health Check 与 Readiness 监控GoFr 在 HTTP 服务器启动时会自动注册健康检查端点见 pkg/gofr/gofr.go 的httpServerSetup/.well-known/alive存活探针liveness返回200 OK可用于 K8s livenessProbe/.well-known/health就绪探针readiness返回应用名与聚合健康状态可用于 K8s readinessProbe。健康检查的响应体实现在 pkg/gofr/health.gohealthResponse只携带name与聚合status两个字段刻意不暴露任何数据源主机、端口、凭据或连接统计等敏感细节。聚合状态取值包括UP全部依赖健康、DEGRADED至少一个依赖不可用、DOWN默认 fail-closed 兜底值。也就是说一个服务只要用gofr.New()启动就天然具备 K8s 健康探针能力无需额外编码。2.4 MetricsPrometheus 格式的指标暴露GoFr 默认在2121 端口的/metrics端点以 Prometheus 文本格式暴露指标用于监控与分析。默认指标覆盖 HTTP 响应耗时、SQL/Redis 耗时、Go 运行时GC 次数、goroutine 数、内存分配、Pub/Sub 计数、重试与熔断状态、GraphQL 操作统计、Cron 任务执行统计等其中常用项包括指标名类型说明app_http_responsehistogramHTTP 请求响应时间秒app_sql_statshistogramSQL 查询响应时间毫秒app_redis_statshistogramRedis 命令响应时间微秒app_go_routinesgauge运行中的 goroutine 数量app_http_circuit_breaker_stategauge熔断器状态0Closed1Openapp_cron_job_total/app_cron_job_successcounterCron 任务执行总数与成功数完整的默认指标清单见 docs/quick-start/observability/page.md。在本地运行时可访问http://localhost:2121/metrics查看原始指标。若要完全禁用 Metrics 服务设置METRICS_PORT0即可对应 pkg/gofr/factory.go 的initMetricsServer实现还可以通过METRICS_CARDINALITY_LIMIT默认 2000限制单指标标签集数量超出部分折叠进otel.metric.overflow序列防止指标基数爆炸。这些指标可直接被 Prometheus 抓取并在 Grafana 中可视化。2.5 Tracing带可追踪 Span 的请求链路GoFr 基于 OpenTelemetry 自动为所有请求与响应导出追踪数据无需额外埋点。每个进入应用的请求会自动生成X-Correlation-ID并写入响应头随后传播到所有下游请求从而可以在分布式系统中用 correlation ID 串起完整调用链。GoFr 的追踪还自动跨越 Pub/Sub 边界Publish时把活动 trace 上下文注入消息头Subscribe时取出作为子 Span使HTTP → publish → subscribe呈现为一条连贯的 trace。追踪导出器通过TRACE_EXPORTER配置支持四种TRACE_EXPORTER说明otlpOpenTelemetry 协议推荐兼容 Jaeger 1.35、Tempo、Honeycomb、OpenTelemetry Collector 等jaeger直连 Jaeger需配置TRACER_URLzipkin旧式 Zipkin官方标注已弃用建议迁移到 OTLPgofrGoFr 自研的 trace 导出器与收集器服务配套的采样配置为TRACER_RATIO取值 0~1默认 1 即全量导出生产建议下调如0.05自定义认证头用TRACER_HEADERS逗号分隔的keyvalue遵循 OpenTelemetry 标准格式。一个完整的 OTLP 配置示例APP_NAMEtest-service HTTP_PORT8000 # tracing configs TRACE_EXPORTERotlp TRACER_URLlocalhost:4317 TRACER_RATIO1.0 LOG_LEVELDEBUG2.6 分级日志的远程动态调整分级日志能力不仅限于启动时静态设置框架内置了远程日志级别变更支持通过REMOTE_LOG_URL指定日志级别下发服务REMOTE_LOG_FETCH_INTERVAL默认 15 秒控制轮询间隔实现生产环境不重启、动态调级的排障体验详见 docs/references/configs/page.md。三、设计原则Principles官方文档 docs/page.md 给出了六条设计原则结合源码可以逐条找到对应的落地方式Promote simple and clean code提倡简单干净的代码Handler 统一为func(ctx *gofr.Context) (any, error)函数签名注册路由只需一行app.GET(/path, handler)见 pkg/gofr/rest.go。Favor compile-time checked code over dynamic code倾向编译期检查而非动态代码Handler 返回值(any, error)、配置读取、路由注册均在编译期做类型约束而不是靠反射/字符串拼接动态生成。Create a solid foundation for the integration of application modules为应用模块集成打牢基础Container统一承载 SQL、Redis、Pub/Sub、HTTP Service、LLM 等模块Handler 通过ctx直接访问模块间解耦见 pkg/gofr/container/container.go。Encourage a more functional way of programming鼓励函数式编程风格Handler 即纯函数式入口——输入Context、输出(data, error)状态与副作用由框架托管天然易于测试可参考 examples/http-server/main.go 中多个 Handler 的写法。Avoid code duplication避免代码重复健康检查、指标、日志、响应信封等横切逻辑全部收敛到框架内部业务代码不重复实现。Log and store data for analysis purposes为分析记录和存储数据日志默认携带trace_id、gofrVersion等结构化字段并支持 JSON 输出配合指标与追踪构成完整可分析数据面。四、五分钟快速上手从零到第一个 REST 服务4.1 前置条件已安装 Go 工具链仓库 README.md 标注要求Go 1.24 及以上快速入门文档 则标注 Go 1.25请以你拉取代码时go.mod声明的版本为准对 Go 基础语法有一定了解。4.2 初始化模块并安装依赖go mod init github.com/example go get gofr.dev4.3 编写第一个服务将以下代码写入main.gopackage main import gofr.dev/pkg/gofr func main() { // 初始化 gofr 对象加载配置、日志、指标、数据源等 app : gofr.New() // 注册 GET /greet 路由 app.GET(/greet, func(ctx *gofr.Context) (any, error) { return Hello World!, nil }) // 启动服务默认监听 8000 端口可通过配置覆盖 app.Run() }4.4 同步依赖并运行go mod tidy go run main.go浏览器访问http://localhost:8000/greet会看到符合 REST 标准的200响应{data:Hello World!}4.5 理解示例的三步gofr.New()初始化框架完成日志、指标、数据源、Tracer、HTTP/gRPC 服务器的装配是所有 GoFr 服务的标准起点见 pkg/gofr/factory.go注册 Handlerapp.GET(/greet, HandlerFunction)把GET /greet映射到处理函数同理可用app.POST(/todo, ...)、app.PUT、app.DELETE、app.PATCH映射其他方法见 pkg/gofr/rest.go。Handler 签名约定为func(ctx *gofr.Context) (any, error)返回响应数据与错误无错误时返回nil。ctx *gofr.Context是对请求、响应与依赖的包装提供参数解析、数据源访问、日志、Span 创建等能力详见 docs/references/context/page.mdapp.Run()配置并启动 HTTP 服务器、中间件、健康检查端点、Metrics 服务等默认监听 8000 端口。五、默认端口与内置端点app.Run()默认会打开两个监听端口使用 gRPC 时增加第三个若端口被占用服务将无法启动可通过configs/.env中的环境变量覆盖默认端口常量定义在 pkg/gofr/default.go服务默认端口覆盖环境变量暴露端点HTTP8000HTTP_PORT业务路由以及/.well-known/health、/.well-known/alive、/.well-known/swagger、/favicon.ico启用 GraphQL 时还有/.well-known/graphql/uiMetricsPrometheus2121METRICS_PORT设为0可禁用/metrics供 Prometheus / kube-prometheus-stack 抓取gRPC9000GRPC_PORT注册的 gRPC 服务仅在调用RegisterService后开启因此一个全新的app : gofr.New(); app.Run()即可访问http://localhost:8000/your-routes业务接口http://localhost:8000/.well-known/alive存活探针K8s liveness 用http://localhost:8000/.well-known/health聚合健康状态 JSONK8s readiness 用http://localhost:2121/metricsPrometheus 指标。所有/.well-known/*路径默认豁免认证健康探针无需携带凭据。全部可配置环境变量见 docs/references/configs/page.md。六、更多开箱即用的生产级能力除了入门文档强调的特性pkg/gofr/gofr.go 中的App还暴露了丰富的扩展点均与入门文档为生产微服务而生的定位一脉相承零样板 REST CRUDapp.AddRESTHandlers(YourStruct{})基于结构体扫描自动注册 CRUD 路由见 pkg/gofr/rest.go数据源接入通过.env配置即自动连接 SQL、Redis、MongoDB、Cassandra、ClickHouse、Pub/Sub 等数据源详见 docs/datasources/getting-started/page.md数据库迁移app.Migrate(migrationsMap)一键执行版本化迁移见 pkg/gofr/gofr.go外部 HTTP 服务调用app.AddHTTPService(name, url)注册带熔断、重试、连接池能力的 HTTP Service参考 examples/http-server/main.goCron 定时任务app.AddCronJob(schedule, name, fn)支持 5/6 段 cron 表达式见 pkg/gofr/gofr.goPub/Sub 订阅app.Subscribe(topic, handler)注册订阅处理函数启动时并发拉起所有订阅者见 pkg/gofr/gofr.go 与 startSubscriptionsgRPC、GraphQL、WebSocket、MCP、LLM分别对应 pkg/gofr/grpc.go、pkg/gofr/graphql.go、pkg/gofr/websocket.go、pkg/gofr/mcp.go、pkg/gofr/ai/llm启动钩子与优雅关闭app.OnStart(func(ctx) error)在服务接收请求前完成初始化如建连、注册app.Shutdown(ctx)按顺序关闭 HTTP/gRPC/Metrics/MCP 服务器并释放数据源连接见 pkg/gofr/gofr.go静态文件服务app.AddStaticFiles(endpoint, filePath)一行注册静态资源目录见 pkg/gofr/gofr.go。仓库 examples 目录提供了 HTTP 服务、Redis、MySQL、gRPC、WebSocket、GraphQL、Cron、文件存储、AI 等大量可直接运行的完整示例是快速上手各模块的最佳参考。七、总结与后续学习路径本文围绕 docs/page.md 完整梳理了 GoFr 的定位、六大核心特性、六条设计原则并给出了可立即运行的快速上手流程。核心要点可概括为一个有主见的框架gofr.New()一行完成装配健康检查、指标、日志、追踪开箱即用零样板 RESTHandler 签名func(ctx *gofr.Context) (any, error) 统一 JSON 信封天然符合 REST 标准生产就绪默认端口与内置端点直接对接 K8s 探针与 PrometheusOTLP/Jaeger 追踪一键开启。继续深入学习建议按以下顺序阅读仓库文档快速入门第一个 GoFr REST API配置参考全部环境变量与默认值可观测性日志、指标与追踪连接 MySQL 与 连接 Redis进阶指南中间件、gRPC、GraphQL、Pub/Sub 等 系列文档examples 目录 中的可运行示例源码与对应测试。【免费下载链接】gofrAn opinionated GoLang framework for accelerated microservice development. Built in support for databases and observability.项目地址: https://gitcode.com/GitHub_Trending/go/gofr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考