Documentation
¶
Overview ¶
Package openapi 提供开放 API 入站网关:第三方通过 AppKey + 签名调用业务接口, 签名校验、时间戳窗口、nonce 防重放、每 App 限流全部由脚手架完成, 业务项目只需像注册普通路由一样注册 handler。
Index ¶
- Constants
- Variables
- func AppKey(ctx iris.Context) string
- func BodySHA256(body []byte) string
- func StringToSign(method, path, timestamp, nonce, bodySHA256 string) string
- func VerifySignature(app *App, method, path, timestamp, nonce, bodySHA256, signature string) error
- type Algorithm
- type App
- type Config
- type MemNonceStore
- type NonceStore
- type OpenAPI
- func (o *OpenAPI) DELETE(path string, handlers ...iris.Handler)
- func (o *OpenAPI) GET(path string, handlers ...iris.Handler)
- func (o *OpenAPI) POST(path string, handlers ...iris.Handler)
- func (o *OpenAPI) PUT(path string, handlers ...iris.Handler)
- func (o *OpenAPI) Party(relative string, handlers ...iris.Handler) iris.Party
- type Registry
- type SetNXFunc
Constants ¶
const ( HeaderAppKey = "X-App-Key" // 应用标识 HeaderTimestamp = "X-Timestamp" // Unix 秒 HeaderNonce = "X-Nonce" // 随机串(防重放) HeaderSignature = "X-Signature" // 签名值 HeaderBodySHA256 = "X-Body-SHA256" // 请求体 SHA256 hex )
签名请求头名称(与出站 thirdparty 客户端对齐)。
const (
// DefaultRatePerSecond 应用默认限流速率。
DefaultRatePerSecond = 100.0
)
ContextKey 网关写入上下文的键。
Variables ¶
var ErrAppExists = errors.New("openapi: app already registered")
ErrAppExists 应用已注册。
Functions ¶
func StringToSign ¶
StringToSign 构建规范化签名串(防篡改:方法/路径/时间戳/随机串/请求体摘要全部参与)。 与出站 thirdparty 的 buildStringToSign 保持一致。
func VerifySignature ¶
VerifySignature 按应用配置的算法校验签名。 app 提供密钥/公钥;签名头值格式:
HMAC: hex(HMAC-SHA256(appSecret, StringToSign)) RSA: base64(RSA-SHA256(publicKey, StringToSign))
Types ¶
type App ¶
type App struct {
// AppKey 应用标识(请求头 X-App-Key 携带)。
AppKey string
// AppSecret HMAC 算法使用的对称密钥(AlgHMAC 时必填)。
AppSecret string
// PublicKey RSA 算法使用的验签公钥(PEM 格式,AlgRSA 时必填)。
PublicKey string
// Algorithm 签名算法,默认 AlgHMAC。
Algorithm Algorithm
// Enabled 是否启用;false 时网关直接拒绝该应用。
Enabled bool
// RatePerSecond 该应用限流速率(每秒令牌数);非正数时默认 100。
RatePerSecond float64
// Burst 突发容量;非正数时取 RatePerSecond。
Burst int
}
App 第三方应用(开放接口调用方)。
type Config ¶
type Config struct {
// Registry 第三方应用注册表(必填)。
Registry *Registry
// NonceStore 防重放存储;nil 时使用内存版(单实例)。
NonceStore NonceStore
// TimestampWindow 时间戳允许偏差;非正数时默认 5 分钟。
TimestampWindow time.Duration
// NonceTTL nonce 保留时长;非正数时默认 10 分钟。
NonceTTL time.Duration
// OnAudit 审计钩子(每次开放接口调用都会回调,含失败请求)。
// 业务可接异步日志队列或数据库;为 nil 时跳过。
OnAudit func(ctx iris.Context, appKey string, ok bool, code apperr.Code)
}
Config 开放网关配置。
type MemNonceStore ¶
type MemNonceStore struct {
// contains filtered or unexported fields
}
MemNonceStore 内存版 nonce 存储(单实例部署;多实例需换 RedisNonceStore)。
type NonceStore ¶
type NonceStore interface {
TrySet(ctx context.Context, key string, ttl time.Duration) (bool, error)
}
NonceStore 定义 nonce 防重放存储。 TrySet 语义与 Redis SETNX 一致:key 不存在时写入并返回 true; 已存在(重复请求)返回 false。ttl 过后 key 自动失效(允许同 nonce 再次使用)。
func NewRedisNonceStore ¶
func NewRedisNonceStore(setNX SetNXFunc) NonceStore
NewRedisNonceStore 创建 Redis 版 nonce 存储。 setNX 传入缓存实现的 SETNX 能力(如 framework/cache 的 TryLock 等价原语)。
type OpenAPI ¶
type OpenAPI struct {
// contains filtered or unexported fields
}
OpenAPI 开放接口注册器。 业务像注册普通路由一样注册 handler,签名校验由网关自动完成:
api := openapi.New(app, openapi.Config{Registry: registry})
api.GET("/v1/order/query", QueryOrder) // 实际路径 /openapi/v1/order/query
api.POST("/v1/order/update", UpdateOrder)
func New ¶
func New(app *iris.Application, cfg Config) *OpenAPI
New 创建开放接口注册器(自动挂载 /openapi 前缀 + 网关中间件)。 app 为 iris 应用;Config.Registry 必填。
Source Files