README
¶
Constant
constant 包定义了微服务通信中通用的 HTTP Header / gRPC Metadata Key。
常用常量
这些常量主要用于 gRPC Metadata 或 HTTP Header 中传递上下文信息。
身份与追踪
Session：会话标识（x-firefly-session）Authorization：认证令牌（authorization）UserId：用户 ID（x-firefly-user-id）AppId：应用 ID（x-firefly-app-id）TenantId：租户 ID（x-firefly-tenant-id）ClientIp：客户端 IP（x-firefly-client-ip）XRealIp：反向代理透传真实 IP（x-real-ip）
链路追踪使用 W3C
traceparent/tracestate（OpenTelemetry 自动注入/提取），本库不再定义自定义 trace 字段常量。
客户端信息
SystemName/SystemVersion：系统名称与版本ClientName/ClientVersion：客户端名称与版本SystemType/ClientType：系统/客户端类型DeviceFormFactor：设备形态AppVersion/AppLanguage：应用版本 / 语言
使用示例
import "google.golang.org/grpc/metadata"
import "github.com/fireflycore/go-micro/rpc"
import "github.com/fireflycore/go-micro/constant"
// 从 gRPC metadata 获取用户信息字段
md, _ := metadata.FromIncomingContext(ctx)
userId, err := rpc.ParseMetaKey(md, constant.UserId)
规范设计
Header Key 命名规范
- 所有自定义 Header Key 必须使用小写字母。
- 单词之间使用短横线
-分隔（kebab-case）。 - 必须使用统一的前缀
x-firefly-，以区别于标准 HTTP Header 或其他框架 Header。
为什么使用静态常量前缀？
我们选择使用硬编码的静态常量前缀（x-firefly-），而不采用运行时动态配置前缀（如 x-{brand}-），基于以下考量：
-
协议标准化（Protocol Standardization）： Header Key 属于通信协议的一部分。如同 HTTP 标准头（
Content-Type）或 OTel 标准头（traceparent）一样，协议的稳定性至关重要。统一的前缀保证了 Firefly 生态内所有组件（网关、SDK、中间件、探针）的无缝互通，无需复杂的协商配置。 -
生态兼容性（Ecosystem Compatibility）： 如果允许不同服务或不同部署环境使用不同的 Header 前缀，会导致跨服务调用、跨品牌合作、以及第三方工具集成变得异常复杂。维护多套协议标准会导致生态割裂。
-
性能与开发体验（Performance & DX）： 静态常量在编译期确定，无运行时拼接开销，且对 IDE 友好（可跳转、可补全）。相比之下，动态前缀需要运行时计算或全局变量注入，增加了初始化复杂度和并发风险。
-
业务隔离（Business Isolation）： 品牌或租户的隔离应当通过 Header Value（如
x-firefly-tenant-id）来实现，而不是通过修改 Header Key。
Documentation
¶
Overview ¶
Package constant 定义微服务通用 header/metadata key。
Index ¶
Constants ¶
View Source
const ( ClientTypeUnspecified = iota // ClientTypeWebBrowser 网页端浏览器 ClientTypeWebBrowser // ClientTypeMiniProgram 小程序 ClientTypeMiniProgram // ClientTypeMobileApp 移动端应用 ClientTypeMobileApp // ClientTypeDesktopApp 桌面端应用 ClientTypeDesktopApp // ClientTypeServer 服务端 ClientTypeServer // ClientTypeEmbedded 嵌入式 ClientTypeEmbedded )
View Source
const ( // DefaultNamespace 默认命名空间 DefaultNamespace = "firefly" // DefaultNetworkSN 默认网卡命名 DefaultNetworkSN = "firefly-main-network" // DefaultExternalNetworkAddress 默认外网地址 DefaultExternalNetworkAddress = "127.0.0.1" // DefaultMaxRetry 默认重试次数 DefaultMaxRetry = 3 // DefaultTTL 默认心跳间隔 DefaultTTL = 10 // DefaultVersion 默认版本号 DefaultVersion = "v0.0.1" )
View Source
const ( // XRealIp 真实ip，一般由nginx设置的 XRealIp = "x-real-ip" // TraceId 为链路追踪 ID（x-trace-id，遵循 OTel 常见实践） TraceId = "x-trace-id" // Authorization 用户token Authorization = "authorization" // HeaderPrefix Firefly系统自定义头部（统一前缀） HeaderPrefix = "x-firefly-" // AccessMethod 访问方式（http2grpc[http-gateway->grpc-gateway], grpc2grpc[grpc-gateway->grpc-service]） AccessMethod = HeaderPrefix + "access-method" AccessMethodHTTP2GRPC = "http2grpc" AccessMethodGRPC2GRPC = "grpc2grpc" // RouteMethod 路由方式（user[user-permission], service[service-permission]） RouteMethod = HeaderPrefix + "route-method" RouteMethodUser = "user" RouteMethodService = "service" // AppLanguage 应用语言 AppLanguage = HeaderPrefix + "app-language" // AppVersion 应用版本 AppVersion = HeaderPrefix + "app-version" // Session 用户session Session = HeaderPrefix + "session" // UserId 用户id UserId = HeaderPrefix + "user-id" // AppId 用户当前的应用Id AppId = HeaderPrefix + "app-id" // TenantId 用户当前应用的归属租户id TenantId = HeaderPrefix + "tenant-id" // OrgIds 用户当前应用下的组织Ids OrgIds = HeaderPrefix + "org-ids" // RoleIds 用户当前应用下的角色Ids RoleIds = HeaderPrefix + "role-ids" // SystemType 客户端系统类型 SystemType = HeaderPrefix + "system-type" // SystemName 客户端系统名称 SystemName = HeaderPrefix + "system-name" // SystemVersion 客户端系统版本 SystemVersion = HeaderPrefix + "system-version" // ClientType 客户端类型 ClientType = HeaderPrefix + "client-type" // ClientName 客户端名称 ClientName = HeaderPrefix + "client-name" // ClientVersion 客户端版本 ClientVersion = HeaderPrefix + "client-version" // HttpGatewaySign HTTP网关签名, 用于跳过GRPC网关认证中间件 HttpGatewaySign = HeaderPrefix + "http-gateway-sign" // GrpcGatewaySign GRPC网关签名, 用于跳过token解析步骤，直接验证用户权限 GrpcGatewaySign = HeaderPrefix + "grpc-gateway-sign" // GatewayAuthSign 网关认证签名, 用于跳过token解析步骤，直接验证用户权限 GatewayAuthSign = HeaderPrefix + "gateway-auth-sign" // InvokeServiceAuth 服务调用相关（Invoke-服务调用方信息，Target-被调用方服务信息） InvokeServiceAuth = HeaderPrefix + "invoke-service-auth" InvokeServiceAppId = HeaderPrefix + "invoke-service-app-id" InvokeServiceEndpoint = HeaderPrefix + "invoke-service-endpoint" TargetServiceAppId = HeaderPrefix + "target-service-app-id" TargetServiceEndpoint = HeaderPrefix + "target-service-endpoint" ClientIp = HeaderPrefix + "client-ip" SourceIp = HeaderPrefix + "source-ip" )
View Source
const ( GrpcAccessLog = "[GRPC Access Log]" HttpAccessLog = "[HTTP Access Log]" )
View Source
const ( RequestMethodGet = iota + 1 RequestMethodPost RequestMethodPut RequestMethodDelete RequestMethodGrpc )
View Source
const ( RequestMethodGetString = "GET" RequestMethodPostString = "POST" RequestMethodPutString = "PUT" RequestMethodDeleteString = "DELETE" RequestMethodGrpcString = "GRPC" )
View Source
const ( SystemTypeUnspecified = iota SystemTypeWindows SystemTypeMacOS SystemTypeLinux SystemTypeAndroid SystemTypeIOS SystemTypeHarmony SystemTypeChromeOS SystemTypeFreeBSD )
View Source
const (
InvokeServiceAuthToken = "invoke-service-auth"
)
View Source
const (
// KernelLanguage 内核开发语言
KernelLanguage = "Golang"
)
Variables ¶
View Source
var RequestMethodMap = map[uint32]string{ RequestMethodGet: RequestMethodGetString, RequestMethodPost: RequestMethodPostString, RequestMethodPut: RequestMethodPutString, RequestMethodDelete: RequestMethodDeleteString, RequestMethodGrpc: RequestMethodGrpcString, }
View Source
var RequestMethodStringMap = map[string]uint32{ RequestMethodGetString: RequestMethodGet, RequestMethodPostString: RequestMethodPost, RequestMethodPutString: RequestMethodPut, RequestMethodDeleteString: RequestMethodDelete, RequestMethodGrpcString: RequestMethodGrpc, }
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files
Click to show internal directories.
Click to hide internal directories.