Service API Design - API Parameter Specification

[Mandatory] Use small camel case for field names

[Mandatory] The return value of the Service API must be wrapped in Response

The return value of the Service API enforces a generic wrapper, for example: Response.
The role of Response:
1. The unified method indicates whether the API call was successful or not
2. When the API call fails, the error Code and Error Message are returned in a unified format.
3. The unified Response is easy to reuse the experience of the caller, and the framework is integrated
As an API caller, its coding requirements are simple:
1. Whether the API call is successful;
2. When the call is unsuccessful, what is the prompt copy;
The caller does not want to:
1. Don't want to care about how awesome the API is
2. Don't want to care about the various Exceptions that the API may throw, and therefore have to do all kinds of exception handling
About the current non-uniform Response
- [New Service] [Mandatory] Use the unified response defined by the architecture group: ZCY Response
- At present, the business side has custom Result/Response, and the style and function are similar. There are better designs that can be recommended to the architecture group for integration, preventing each other from developing and duplicating new definitions.

[Mandatory] Put an end to completely irregular abbreviations, and avoid ignoring the meaning of the text. (except international abbreviations)

wrong practice
- AbstractClass "abbreviation" named AbsClass;
- The condition "abbreviation" is named condi;
- Such arbitrary abbreviations seriously reduce the readability of the code.

[Mandatory] It is forbidden to use Map as parameter type

The Map<K,V> mechanism is very flexible, but such flexibility has a huge negative effect.

The data description of Map is obscure. There needs to be an implicit contract between the caller and the implementer to explain which keys are supported and what type of value each key is. Increase the complexity of the use of both sides.
Map<K,V> cannot be verified. Coupled with the complexity of the use of Article 1, it is very error-prone in use.
The design of reserved extensibility with Map type fields is an inelegant design.

Note: The caller custom data section in the parameters allows the use of Map. The API provider is irrelevant, does not parse, and only transmits transparently.

[Mandatory] The business object/query condition is encapsulated with DTO, and it is forbidden to tile fields as input parameters.

correct practice

Paging query, wrap the query conditions in DTO mode.

Dubbo serialization features:

In the POJO class of Dubbo API, the UID is inconsistent: it doesn't matter.
In the POJO class of Dubbo API, the number of fields is inconsistent: it doesn't matter, as long as the field name and type are the same, the data can be deserialized successfully.
The sender has more fields than the receiver: it doesn't matter.
The sender has fewer fields than the receiver: it doesn't matter.

1	Response<Page<T>> pagingXXX(QueryDTO q)

wrong practice

1	Response<Page<T>> pagingXXX(String name, String code, Long orgId, Long creatorId, Integer pageNo, Integer PageSize)

Disadvantages of the above wrong practice:
1. For the caller, no matter what conditions are used to query, it is necessary to pass parameters one by one.
2. The API is not friendly to expansion. Once you want to add query conditions, the API is not compatible.

[Recommended] Set JSR303 Annotation in DTO field for basic verification

correct practice

1
2
3

public interface ZcyPayFacade {
    Result<Boolean> validTradePay(@NotNull @Valid TradePayPO tradePayPO);
}

public class TradePayPO implements Serializable {

    @NotBlank
    @Length(max = 15)
    /** Business transaction number (order number) */
    private String businessTradeNo;

    /**
     * Business channel: 1-Subscription, 2-CA
     * @see BusinessTypeEnum
     *
     * */
    @NotNull
    @Range(min = 1, max = 2)
    private Integer businessType;

    ......
    
    /** Merchant name (merchant) */
    @NotBlank
    @Length(max = 50)
    private String merchantName;

    /** Order title (ie item name), which roughly describes the user's payment purpose. Such as "Consumption at Xisto (Pudong Store)"*/
    @NotBlank
    @Length(max = 256)
    private String orderSubject;

    /** Order description (ie product description), you can give a detailed description of the transaction or product, for example, fill in "buy 2 items for a total of 15.00 yuan"*/
    @NotBlank
    @Length(max = 128)
    private String orderBody;

    ......
}

[Recommended] Complete the basic field verification on the client side

Method 1: [Recommended] Customize Dubbo Filter to achieve general interception and verification.
Method 2: [Recommended] Build the input object through the Builder mode.
Method 3: [Not recommended] Dubbo client parameter verification, require the consumer to set validation=”true”, and Dubbo client parameter verification . Disadvantage: Handling verification failures by throwing exceptions requires the business side to additionally handle Exceptions. Moreover, the IDE does not prompt the consumer side to handle the ConstraintViolationException.
Mode 4: Dubbo mode, local-stub feature. The implementation is more complicated, and the verification code has low versatility. Dubbo local-stub