trafficctrl

package
v0.0.0-...-8932ee7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 2, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EvalCEL 

func EvalCEL(expression string, attrs map[string]any) bool

EvalCEL 对属性 map 执行 CEL 表达式，返回布尔结果。 表达式中用 attrs["field"] 或 attrs.field 引用属性。

func SignalToBoostFactor 

func SignalToBoostFactor(signal, maxFactor float64) float64

SignalToBoostFactor 将 PID 输出信号转换为加权系数。 signal > 0 → factor > 1（提升）；signal < 0 → factor < 1（抑制）。 使用 sigmoid 映射，signal=0 时 factor≈1.0。

Types

type Audience 

type Audience struct {
	RuleSet
}

Audience 人群圈选配置。

type BoostEvent 

type BoostEvent struct {
	TaskID      string  `json:"task_id"`
	ItemID      string  `json:"item_id"`
	UserID      string  `json:"user_id"`
	Scene       string  `json:"scene"`
	BoostFactor float64 `json:"boost_factor"`
	OrigScore   float64 `json:"orig_score"`
	NewScore    float64 `json:"new_score"`
	Position    int     `json:"position"`
}

BoostEvent 单次调控行为记录。

type BoostType 

type BoostType string

BoostType 调控执行策略类型。 

const (
	BoostTypeWeight BoostType = "weight" // 直接加权（无反馈闭环）
	BoostTypePID    BoostType = "pid"    // PID 闭环控制
	BoostTypePin    BoostType = "pin"    // 置顶（强插指定位置）
)

type DiversityConfig 

type DiversityConfig struct {
	WindowSize int `json:"window_size"` // 滑动窗口大小
	MaxBoosted int `json:"max_boosted"` // 窗口内最多允许的被调控物品数
	MinGap     int `json:"min_gap"`     // 被调控物品之间的最小间隔
}

DiversityConfig 被调控物品的多样性约束。

func (*DiversityConfig) HasDiversity 

func (d *DiversityConfig) HasDiversity() bool

HasDiversity 是否配置了多样性约束。

type EventEmitter 

type EventEmitter interface {
	EmitBoostEvent(ctx context.Context, event BoostEvent)
}

EventEmitter 调控事件上报端口（异步，不阻塞主流程）。

type Granularity 

type Granularity string

Granularity 目标颗粒度。 

const (
	GranularityGlobal  Granularity = "global"
	GranularityPerItem Granularity = "per_item"
)

type ItemPool 

type ItemPool struct {
	Type      ItemPoolType `json:"type"`
	RuleSet                // 动态规则匹配
	StaticIDs []string     `json:"static_ids,omitempty"`
}

ItemPool 物品池配置。

func (*ItemPool) ContainsID 

func (p *ItemPool) ContainsID(id string) bool

ContainsID 判断给定 ID 是否在静态列表中。

func (*ItemPool) HasStaticIDs 

func (p *ItemPool) HasStaticIDs() bool

HasStaticIDs 判断物品池是否包含静态 ID 列表。

func (*ItemPool) MatchItem 

func (p *ItemPool) MatchItem(id string, attrs map[string]any) bool

MatchItem 判断 item 属性是否满足物品池条件。

type ItemPoolType 

type ItemPoolType string

ItemPoolType 物品池类型。 

const (
	ItemPoolDynamic ItemPoolType = "dynamic"
	ItemPoolStatic  ItemPoolType = "static"
	ItemPoolMixed   ItemPoolType = "mixed"
)

type Metric 

type Metric string

Metric 调控指标。 

const (
	MetricExposureCount Metric = "exposure_count"
	MetricExposureRatio Metric = "exposure_ratio"
	MetricClickCount    Metric = "click_count"
	MetricInteractRate  Metric = "interaction_rate"
)

type MetricsReader 

type MetricsReader interface {
	GetMetric(ctx context.Context, taskID string, metric Metric, window string) (float64, error)
}

MetricsReader 实时指标读取端口（PID 闭环依赖）。

type Operator 

type Operator string

Operator 规则条件运算符。 

const (
	OpEq       Operator = "=="
	OpNe       Operator = "!="
	OpGt       Operator = ">"
	OpGte      Operator = ">="
	OpLt       Operator = "<"
	OpLte      Operator = "<="
	OpIn       Operator = "in"
	OpNotIn    Operator = "not_in"
	OpContains Operator = "contains"
)

type PIDController 

type PIDController struct {
	// contains filtered or unexported fields
}

PIDController 位置式 PID 控制器，用于流量调控的闭环反馈。

工作原理：

  • 输入：目标值与当前实际值的偏差 (error)
  • 输出：排序分加权信号 (boost signal)
  • P: 当前偏差越大，调控力度越大
  • I: 累积偏差用于消除稳态误差（限幅 ±100 防 windup）
  • D: 偏差变化率用于抑制振荡

func NewPIDController 

func NewPIDController(params PIDParams) *PIDController

NewPIDController 创建 PID 控制器。

func (*PIDController) FromState 

func (c *PIDController) FromState(state PIDState)

FromState 从持久化状态恢复。

func (*PIDController) Reset 

func (c *PIDController) Reset()

Reset 重置控制器状态。

func (*PIDController) ToState 

func (c *PIDController) ToState(taskID string, lastOutput float64) PIDState

ToState 导出当前状态。

func (*PIDController) Update 

func (c *PIDController) Update(err float64) float64

Update 输入当前误差，返回调控信号。 error = target - current；正值表示需要更多流量。

type PIDParams 

type PIDParams struct {
	Kp float64 `json:"kp"`
	Ki float64 `json:"ki"`
	Kd float64 `json:"kd"`
}

PIDParams PID 控制器参数。

type PIDState 

type PIDState struct {
	TaskID     string  `json:"task_id"`
	PrevError  float64 `json:"prev_error"`
	Integral   float64 `json:"integral"`
	Iterations int     `json:"iterations"`
	LastOutput float64 `json:"last_output"`
}

PIDState 可序列化的 PID 状态，用于跨请求持久化。

type PIDStateStore 

type PIDStateStore interface {
	Load(ctx context.Context, taskID string) (PIDState, error)
	Save(ctx context.Context, state PIDState) error
}

PIDStateStore PID 状态持久化端口（跨请求保持积分项等）。

type Rule 

type Rule struct {
	Field string   `json:"field"`
	Op    Operator `json:"op"`
	Value any      `json:"value"`
}

Rule 单条规则条件。

func (*Rule) Match 

func (r *Rule) Match(attrs map[string]any) bool

Match 判断给定属性值是否满足规则。

type RuleSet 

type RuleSet struct {
	Rules      []Rule `json:"rules,omitempty"`
	Expression string `json:"expression,omitempty"` // CEL 表达式（优先于 Rules）
}

RuleSet 规则集合，所有规则取 AND 关系。

func (*RuleSet) MatchAll 

func (rs *RuleSet) MatchAll(attrs map[string]any) bool

MatchAll 判断属性是否满足规则集。 优先级：Expression（CEL）> Rules（AND）。空规则集匹配全部。

type Schedule 

type Schedule struct {
	StartTime        time.Time `json:"start_time"`
	EndTime          time.Time `json:"end_time"`
	DailyActiveHours [2]int    `json:"daily_active_hours"` // [startHour, endHour)，空则全天
}

Schedule 任务时间调度。

func (*Schedule) InWindow 

func (s *Schedule) InWindow(now time.Time) bool

InWindow 判断给定时间是否在调控窗口内。

type Strategy 

type Strategy struct {
	BoostType      BoostType       `json:"boost_type"`
	PIDParams      PIDParams       `json:"pid_params,omitempty"`
	BoostFactor    float64         `json:"boost_factor,omitempty"`
	MaxBoostFactor float64         `json:"max_boost_factor,omitempty"`
	FallbackBoost  float64         `json:"fallback_boost,omitempty"`
	PinPositions   []int           `json:"pin_positions,omitempty"`
	Diversity      DiversityConfig `json:"diversity"`
}

Strategy 调控执行策略。

func (*Strategy) EffectiveMaxBoost 

func (s *Strategy) EffectiveMaxBoost() float64

EffectiveMaxBoost 有效最大加权倍数（默认 5.0）。

type Target 

type Target struct {
	Name        string      `json:"name"`
	Type        TargetType  `json:"type"`
	Metric      Metric      `json:"metric"`
	Value       float64     `json:"value"`
	Tolerance   float64     `json:"tolerance"`
	Granularity Granularity `json:"granularity"`
	Window      string      `json:"window"` // 统计时间窗口
}

Target 调控目标定义。

func (*Target) Error 

func (t *Target) Error(currentValue float64) float64

Error 计算目标偏差（PID 控制器输入）。 正值 = 需要更多流量，负值 = 需要减少流量。

func (*Target) IsSatisfied 

func (t *Target) IsSatisfied(currentValue float64) bool

IsSatisfied 判断当前指标值是否满足目标。

type TargetType 

type TargetType string

TargetType 调控目标类型。 

const (
	TargetGuarantee   TargetType = "guarantee"   // 保量：≥ 目标值
	TargetApproximate TargetType = "approximate" // 逼近：≈ 目标值
	TargetBoost       TargetType = "boost"       // 加权：分数乘以系数
	TargetSuppress    TargetType = "suppress"    // 打压：分数乘以 <1 系数
	TargetPin         TargetType = "pin"         // 置顶：强制前 N 位
)

type Task 

type Task struct {
	ID       string     `json:"task_id"`
	Name     string     `json:"name"`
	Scene    string     `json:"scene"`
	Status   TaskStatus `json:"status"`
	Priority int        `json:"priority"` // 数字越大优先级越高

	Schedule Schedule `json:"schedule"`
	Audience Audience `json:"audience"`
	ItemPool ItemPool `json:"item_pool"`
	Targets  []Target `json:"targets"`
	Strategy Strategy `json:"strategy"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Task 流量调控任务：运营管理的最小调控单元。

func (*Task) IsActive 

func (t *Task) IsActive(now time.Time) bool

IsActive 判断任务当前是否活跃（状态 + 时间窗口）。

type TaskRepository 

type TaskRepository interface {
	GetActiveTasks(ctx context.Context, scene string) ([]*Task, error)
	GetTask(ctx context.Context, taskID string) (*Task, error)
}

TaskRepository 任务配置读取端口。

type TaskStatus 

type TaskStatus string

TaskStatus 任务状态。 

const (
	TaskStatusDraft     TaskStatus = "DRAFT"
	TaskStatusActive    TaskStatus = "ACTIVE"
	TaskStatusPaused    TaskStatus = "PAUSED"
	TaskStatusCompleted TaskStatus = "COMPLETED"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.