CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-sentinel-parameter-flow-control

Sentinel Parameter Flow Control provides functionality of flow control by frequent (hot spot) parameters.

—

Pending
Overview
Eval results
Files

exception-items.mddocs/

Exception Items

Special parameter values that have different thresholds than the default rule. ParamFlowItem allows you to configure different limits for specific parameter values, enabling VIP user handling, special case parameters, and fine-grained parameter-based flow control.

Capabilities

Basic Item Creation

Creates exception items for specific parameter values with custom thresholds.

/**
 * Default constructor for parameter flow item
 */
public ParamFlowItem();

/**
 * Constructor with all parameters
 * @param object the parameter value as string
 * @param count the threshold count for this parameter value
 * @param classType the class type of the parameter
 */
public ParamFlowItem(String object, Integer count, String classType);

Usage Example:

// Create exception item manually
ParamFlowItem item = new ParamFlowItem("VIP_USER", 50, String.class.getName());

// Or create with default constructor and set properties
ParamFlowItem item2 = new ParamFlowItem();
item2.setObject("ADMIN_USER")
     .setCount(100)
     .setClassType(String.class.getName());

Static Factory Method

Creates exception items using a type-safe factory method.

/**
 * Create a new parameter flow item with type safety
 * @param object the parameter value object
 * @param count the threshold count for this parameter value
 * @param <T> the type of the parameter
 * @return new ParamFlowItem instance
 * @throws IllegalArgumentException if object is null
 */
public static <T> ParamFlowItem newItem(T object, Integer count);

Usage Example:

// Type-safe creation for different parameter types
ParamFlowItem stringItem = ParamFlowItem.newItem("VIP_USER", 50);
ParamFlowItem intItem = ParamFlowItem.newItem(12345, 25);
ParamFlowItem longItem = ParamFlowItem.newItem(999999L, 75);

// Class type is automatically set based on the object type
System.out.println(stringItem.getClassType()); // java.lang.String
System.out.println(intItem.getClassType());    // java.lang.Integer
System.out.println(longItem.getClassType());   // java.lang.Long

Parameter Value Configuration

Configures the specific parameter value that should receive special treatment.

/**
 * Set the parameter value as string representation
 * @param object the parameter value
 * @return this item for method chaining
 */
public ParamFlowItem setObject(String object);

/**
 * Get the parameter value
 * @return parameter value as string
 */
public String getObject();

Usage Example:

// Configure different types of parameter values
ParamFlowItem userItem = new ParamFlowItem()
    .setObject("admin@company.com")  // Email-based parameter
    .setCount(100);

ParamFlowItem productItem = new ParamFlowItem()
    .setObject("PRODUCT_12345")      // Product ID parameter
    .setCount(200);

ParamFlowItem numericItem = new ParamFlowItem()
    .setObject("999")                // Numeric parameter as string
    .setCount(50);

Threshold Configuration

Sets the custom threshold for the specific parameter value.

/**
 * Set the threshold count for this parameter value
 * @param count the threshold count
 * @return this item for method chaining
 */
public ParamFlowItem setCount(Integer count);

/**
 * Get the threshold count
 * @return threshold count
 */
public Integer getCount();

Usage Example:

// Different thresholds for different user types
ParamFlowItem regularUser = new ParamFlowItem()
    .setObject("REGULAR_USER")
    .setCount(10);  // 10 QPS for regular users

ParamFlowItem vipUser = new ParamFlowItem()
    .setObject("VIP_USER")
    .setCount(50);  // 50 QPS for VIP users

ParamFlowItem premiumUser = new ParamFlowItem()
    .setObject("PREMIUM_USER")
    .setCount(100); // 100 QPS for premium users

Class Type Configuration

Specifies the Java class type of the parameter for proper type conversion.

/**
 * Set the class type of the parameter
 * @param classType the fully qualified class name
 * @return this item for method chaining
 */
public ParamFlowItem setClassType(String classType);

/**
 * Get the class type
 * @return class type name
 */
public String getClassType();

Usage Example:

// Configure class types for different parameter types
ParamFlowItem stringParam = new ParamFlowItem()
    .setObject("VIP_123")
    .setClassType(String.class.getName())
    .setCount(50);

ParamFlowItem intParam = new ParamFlowItem()
    .setObject("12345")
    .setClassType(Integer.class.getName())  // Will be parsed as Integer
    .setCount(25);

ParamFlowItem longParam = new ParamFlowItem()
    .setObject("999999999")
    .setClassType(Long.class.getName())     // Will be parsed as Long
    .setCount(75);

ParamFlowItem boolParam = new ParamFlowItem()
    .setObject("true")
    .setClassType(Boolean.class.getName())  // Will be parsed as Boolean
    .setCount(100);

Supported Parameter Types

The following Java types are supported for parameter value parsing:

  • String - Direct string matching (default if no class type specified)
  • Integer / int - Parsed using Integer.parseInt()
  • Long / long - Parsed using Long.parseLong()
  • Double / double - Parsed using Double.parseDouble()
  • Float / float - Parsed using Float.parseFloat()
  • Boolean / boolean - Parsed using Boolean.parseBoolean()
  • Byte / byte - Parsed using Byte.parseByte()
  • Short / short - Parsed using Short.parseShort()
  • Character / char - Uses first character of string

Complete Usage Example

import com.alibaba.csp.sentinel.slots.block.flow.param.*;
import java.util.Arrays;

// Create parameter flow rule with multiple exception items
ParamFlowRule rule = new ParamFlowRule("userService")
    .setParamIdx(0)
    .setCount(10);  // Default: 10 QPS for regular users

// Create exception items for different user types
ParamFlowItem vipUser = ParamFlowItem.newItem("VIP_USER", 50);
ParamFlowItem adminUser = ParamFlowItem.newItem("ADMIN_USER", 100);
ParamFlowItem guestUser = ParamFlowItem.newItem("GUEST_USER", 5);

// Numeric parameter exceptions
ParamFlowItem highPriorityProduct = new ParamFlowItem()
    .setObject("12345")
    .setClassType(Integer.class.getName())
    .setCount(200);

ParamFlowItem lowPriorityProduct = new ParamFlowItem()
    .setObject("99999")
    .setClassType(Integer.class.getName())
    .setCount(2);

// Apply all exception items to the rule
rule.setParamFlowItemList(Arrays.asList(
    vipUser, adminUser, guestUser, highPriorityProduct, lowPriorityProduct
));

// Load the rule
ParamFlowRuleManager.loadRules(Arrays.asList(rule));

// Usage in application:
// processUser("VIP_USER")      -> 50 QPS limit
// processUser("ADMIN_USER")    -> 100 QPS limit
// processUser("GUEST_USER")    -> 5 QPS limit
// processUser("REGULAR_USER")  -> 10 QPS limit (default)
// processProduct(12345)        -> 200 QPS limit
// processProduct(99999)        -> 2 QPS limit
// processProduct(55555)        -> 10 QPS limit (default)

Runtime Behavior

When a parameter flow rule is evaluated:

  1. The parameter value at the specified index is extracted
  2. The value is converted to string representation
  3. Exception items are checked for exact matches
  4. If a match is found, the exception item's count is used
  5. If no match is found, the rule's default count is used
  6. Type conversion is performed based on the configured class type

Thread Safety

ParamFlowItem objects are immutable once created and configured. All getter and setter operations are thread-safe. However, you should not modify exception items after they have been added to a rule that is already loaded into ParamFlowRuleManager.

Install with Tessl CLI

npx tessl i tessl/maven-sentinel-parameter-flow-control

docs

cluster-mode.md

exception-items.md

flow-control-exceptions.md

index.md

parameter-flow-rules.md

rule-management.md

tile.json