SDS Downgrade Points Naming Conventions and Management Practices

SDS downgrade points use camel-case Java variable naming (e.g., createOrderPoint), must be unique per application, and are centrally managed in the SDS admin database through auto-registration and periodic cleanup.

In the didi/sds (Service Degradation System) repository, a downgrade point serves as a unique string identifier that protects specific business methods from cascading failures. Understanding the proper SDS downgrade points naming conventions and management practices ensures your degradation strategy remains readable, consistent, and synchronized across distributed services.

Naming Conventions for SDS Downgrade Points

Camel-Case Formatting

According to the README documentation, SDS adopts Java variable naming conventions for point strings to maintain aesthetic consistency. The documentation states that points should follow the camel-case style (驼峰法), resembling standard Java variable names such as businessMethodPoint.

Centralized Constant Definitions

Production implementations should declare downgrade points as public static final String constants within dedicated constant files. In sds-example/sds-client-example/src/main/java/com/didiglobal/sds/example/chapter4/OrderManageService.java, the project defines:

public final static String CREATE_ORDER_POINT = "createOrderPoint";

This approach enables reuse across multiple service methods and prevents hardcoding strings throughout the codebase.

Business Meaning and Uniqueness

Effective point names must convey the specific business operation they protect, such as createOrderPoint or queryUserInfoPoint. The system enforces uniqueness within each application through validation logic. In SdsClient, SdsPowerfulCounterService, and other client APIs, the code invokes AssertUtil.notBlack(point, "降级点不能为空！") to ensure the point string is non-blank and valid.

Management Practices for SDS Downgrade Points

Central Registration in Point Dictionary

Every downgrade point requires persistence in the SDS admin database, specifically the point_dict table. The PointDictServiceImpl.addIfNotExist() method in sds-admin/src/main/java/com/didiglobal/sds/admin/service/impl/PointDictServiceImpl.java handles this by inserting new points only when they do not already exist in the database.

Batch Registration and Duplicate Prevention

For bulk operations, the addPointList() method iterates through point collections, skips existing entries, and inserts only new records. This prevents duplicate entries while efficiently registering multiple points during application deployment or updates.

Automatic Cleanup of Dead Points

The admin service periodically purges obsolete points that no longer appear in client heartbeat data. The checkAndDeleteDeadPoint() method compares the database dictionary against live client heartbeat maps, removing stale entries to maintain a clean configuration state.

Client-Side Usage Patterns

Developers reference the constant definitions through three primary integration patterns:

1. Direct API calls to SdsClient methods: shouldDowngrade(), exceptionSign(), and downgradeFinally()
2. AOP annotation using @SdsDowngradeMethod(point = CREATE_ORDER_POINT) as demonstrated in OrderManageService.java
3. Utility wrapper via SdsEasyUtil.invokerMethod() for simplified three-step execution

Implementation Examples

The following patterns demonstrate practical application of these conventions.

Centralized constant definition:

public final class DowngradePoints {
    public static final String CREATE_ORDER_POINT = "createOrderPoint";
    public static final String QUERY_USER_POINT   = "queryUserInfoPoint";
}

Direct client API usage:

if (sdsClient.shouldDowngrade(DowngradePoints.CREATE_ORDER_POINT)) {
    throw new SdsException("Order creation degraded");
}
try {
    // business logic
} catch (Exception e) {
    sdsClient.exceptionSign(DowngradePoints.CREATE_ORDER_POINT, e);
    throw e;
} finally {
    sdsClient.downgradeFinally(DowngradePoints.CREATE_ORDER_POINT);
}

AOP annotation approach:

@Service
public class OrderService {
    @SdsDowngradeMethod(point = DowngradePoints.CREATE_ORDER_POINT)
    public Long createOrder(Long userId, String address) {
        return ThreadLocalRandom.current().nextLong(0, 10_000_000);
    }
}

Utility helper pattern:

String result = SdsEasyUtil.invokerMethod(
        DowngradePoints.QUERY_USER_POINT,
        "defaultUser",
        () -> userRepository.findById(id).orElseThrow());

Summary

• SDS downgrade points must follow camel-case Java variable naming conventions for consistency and readability.
• Define points as public static final String constants in dedicated files to ensure reuse and prevent duplication.
• The PointDictServiceImpl in the admin module handles central registration, batch insertion, and automatic cleanup of dead points through methods like addIfNotExist() and checkAndDeleteDeadPoint().
• Client applications enforce point validity through AssertUtil.notBlack() validation before executing degradation logic.
• Integration options include direct SdsClient API calls, @SdsDowngradeMethod annotations, or the simplified SdsEasyUtil wrapper.

Frequently Asked Questions

What happens if two different methods use the same downgrade point name in the same application?

The SDS system requires uniqueness within each application. While the client-side AssertUtil.notBlack() validation ensures the point is non-blank, duplicate point names for different logical operations would cause incorrect degradation statistics and strategy application. Each business operation should have a distinct point constant like createOrderPoint versus updateOrderPoint.

How does SDS handle point registration when deploying a new service instance?

When a client application starts, it sends heartbeat data containing active downgrade points to the SDS admin service. The PointDictServiceImpl.addIfNotExist() method automatically persists any new points to the point_dict table without requiring manual database insertion, enabling zero-touch registration during deployment.

What is the recommended way to clean up unused downgrade points?

The SDS admin service runs checkAndDeleteDeadPoint() periodically to compare registered points against active client heartbeats. Points that no longer appear in heartbeat data are automatically removed from the database, preventing configuration clutter from deprecated business methods.

Can I use Chinese characters or special symbols in downgrade point names?

While technically possible if the string passes validation, the didi/sds README explicitly recommends camel-case English naming following Java variable conventions (e.g., businessMethodPoint). This ensures compatibility, readability, and consistency across international development teams.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}