Thinking and precipitation after docking with hundreds of third-party APIs

Hello everyone , I'm orange , One  Java  The engineer .

Some time ago, I read an article about docking with third parties written by my peers , That article “ Focus on how to teach you docking ” This process , Juchang thinks there are some better supplements and thoughts , So write this long article , Interested can wx Search for ： Long orange said Java.

One 、 Chat with third parties

Two common functions are listed , One is to send the verification code according to the number , Second, wechat authorization 、 Payment and other functions ,

The third party is actually short for , More accurately, it should describe the capabilities provided by third-party service providers  Api  Interface .

One ） Why is there such a supplier of third-party functions ？

In essence, the market has relevant demand , Customers spend money on services , Be a service aggregator

, The SMS functions listed above belong to the business side functional requirements , As a family  IT  The company has two choices for such functions , One is to sign relevant contracts with operators , The second is to find a company that has encapsulated the SMS service .

At present, there are many orange growing experiences in option 2 , Find a competent company , They provide short message capability up to the customer side , Encapsulate the troublesome details related to the interaction with the operator , Draw a maid .

Two ） Provided by the supplier  Api  Ability

Generally speaking , Generally, call the service provider's  Api  All are server-side communication behaviors , It is rare for a client to make a request directly to a vendor  Api  Related operations of , Why? , From a security point of view .

For suppliers , Their service and customers are a one to many relationship , Then it is necessary to do a good job in the relevant management of customer keys and other information , For clients , Just focus on  api  The logic of interaction is enough , Today we mainly want to share the client side , Suppliers need to manage customer related information , You can think about it by yourself .

Two 、 Third party concerns and considerations

One ） concerns

1、 Service provider

Here is a guiding principle ： Documents are written for people to see , Not for the machine .

So one thing to note about service providers is documentation , A slightly better team will create a static content aggregation page , For example, related documents of enterprise wechat ：

https://developer.work.weixin.qq.com/document/path/91201

,

A slightly average team will write and maintain an online document , For example, the language bird knowledge base 、 Graphite these .

What does the worse team do ？ Write  word  file , There is no idea of version management , It is often different ways that lead to huge differences in communication costs .

Writing documents serves two purposes , First, tell the outside world that our technical team is professional , Put... In the document  api  Detailed description of input and output parameters of , Version change 、 Interaction sequence diagrams are clearly recorded , Second, from the perspective of customers , Consider their user experience , Many customers complain that the documents are poorly written , The actual parameters and responses differ greatly from the documentation , I really can't figure out why they don't pay attention to this document .

The most common reason is ： Our service provider development team is busy , There is no time to sustain those , Communicating these times is a bad result , I'd rather slow down , Please don't make such a mess .

2、 Service access provider

The first thing, of course, is to read the document , So from the perspective of customer experience , Does the service provider have to write a good document ,

Looking at documents usually focuses on two , One is  API  Interactive authentication problem , The second is the encryption and decryption of data transmission .

API  Interactive authentication problem ： The solution is mutual authentication , That is who you are , Whether it is a trusted customer we have recorded .

Encryption and decryption of data transmission ： It solves the problem of data security , Whether it has been edited , Encryption algorithm with symmetric or asymmetric details .

Two ） Pay attention to item

This article is mainly about service access , Therefore, the attention item will also focus on the access , Access must be logical , In fact, it's about rules , See the steps required by the service provider step by step .

For example ： First file the application and fill in the relevant materials 、 Then obtain the relevant configuration issued by the service provider 、 Use  postman  etc.  api  The tool first tries to see if the network is smooth 、 The next step is to write code to connect this fast 、 And then integrated into the business side .

Here are some code side considerations .

1、 Pull away code that interacts with third parties

The following is a list of relevant codes using the SMS service of Alibaba as an example .

1） Customize a  AliApiServerException  It's abnormal

/**
 * AliAPIServerException
 *
 * @author AFlymamba
 */
@Getter
@NoArgsConstructor
@AllArgsConstructor
public class AliApiServerException extends Exception {
 private static final long serialVersionUID = -3064220748468350413L;
 String message;
}


Be careful ： What is inherited here is  Exception, Instead of what is routinely recommended  RuntimeException.

2） Construct a  AliApiServerService

/**
 * AliApiServerService
 * <p>
 * bad response：result=0&errMsg=xxx
 *
 * @author AFlymamba
 */
public interface AliApiServerService {
 /**
 * Send Single Message
 *
 * @param phone Mobile
 * @param content content
 * @return send result
 * @throws AliApiServerException Server Exception
 */
 JSONObject sendSingleMessage(String phone, String content) throws AliApiServerException;
}


A better way to do this is to refer to the recommended object by the method , Out reference  JSON, But many third parties  api  fool around with , They return directly to a non  json  Format , Direct to  String, The above code comments give a bad example , Out of respect , It's unified here  json, Then declare at the method that a custom exception may be thrown .

3） structure  AliApiServiceImpl

/**
 * AliApiServerServiceImpl
 *
 * @author AFlymamba
 */
@Slf4j
@Service
public class AliApiServerServiceImpl implements AliApiServerService {
 @Override
 public JSONObject sendSingleMessage(final String phone, final String content) throws AliApiServerException {
 // ignore phone、content check
 String requestUrl = StrBuilder.create("http://xxx").append("/api/v1/xxx").toString();
 JSONObject requestBody = JSONUtil.createObj().putOnce("phone", phone).putOnce("content", content);
 // ignore header、encrypt、sign
 try {
 String responseBody = HttpRequest.post(requestUrl).body(requestBody.toString()).timeout(3000).execute().body();
 log.info("[ AliApiServer ] sendSingleMessage,requestUrl is [{}],requestBody is [{}], origin response is [{}]", requestUrl, requestBody, responseBody);
 if (JSONUtil.isJson(responseBody)) {
 return JSONUtil.parseObj(responseBody);
 }
 } catch (Exception e) {
 log.error("[ AliApiServer ] sendSingleMessage exception,requestUrl is [{}],requestBody is [{}],exception message is [{}],cause is [{}]", requestUrl, requestBody, e.getMessage(), e.getCause());
 }
 throw new AliApiServerException("AliApiServerException, please check log......");
 }
}


The above code diagram eliminates the relevant verification , Who also obtain third-party services  url  And other parameters are also staticized , Pure laziness , A more reasonable course of action is  load from config or db. Again  log print  There is something wrong with that piece , A unique identification is not printed , For example, service providers  id、 user  id  Etc , Long orange gave you an example of the a mistake , Cautionary tale .

2、 Interaction between business side and third-party interaction code

After the above code for interacting with the third party is completed , In fact, we have integrated the capabilities of the third party and exposed them in the form of interfaces , Next, let's do some business side and third-party interaction demonstrations and optimization .

Here are three blocks of code , Namely  ActivityServiceImpl、MessageServiceImpl、AliApiServiceImpl, Briefly explain the following ,Activity  That belongs to the business site ,Message  This belongs to the intermediate layer transition point ,AliApi  This is a point of interaction with third parties , The following code is for demonstration , A lot of specification issues are ignored , understanding .

1） The business point and the third-party interaction point directly invoke

/**
 * ActivityServiceImpl
 *
 * @author AFlymamba
 */
@Slf4j
@Service
public class ActivityServiceImpl implements ActivityService {
 private final AliApiServerService aliApiServerService;
 
 @Autowired
 public ActivityServiceImpl(
 AliApiServerService aliApiServerService
 ) {
 this.aliApiServerService = aliApiServerService;
 }
 @Override
 public void sendMessage(final String phone, final String content) {
 // ignore
 try {
 JSONObject sendResult = aliApiServerService.sendSingleMessage(phone, content);
 } catch (AliApiServerException e) {
 // ignore
 }
 }
}


amount to  ActivityServiceImpl  Directly coupled  AliApiServerService.

2） introduce  MessageServiceImpl  To decouple the coupling point of mode 1

@Slf4j
@Service
public class MessageServiceImpl extends MessageService {
 private final AliApiServerService aliApiServerService;
 @Autowired
 public MessageServiceImpl(
 AliApiServerService aliApiServerService
 ) {
 this.aliApiServerService = aliApiServerService;
 }
 @Override
 public void sendMessage(final String phone, final String content) {
 // ignore
 try {
 JSONObject sendResult = aliApiServerService.sendSingleMessage(phone, content);
 } catch (AliApiServerException e) {
 // ignore
 }
 }
}

//  Code adjustment in method 1 above
@Slf4j
@Service
public class ActivityServiceImpl implements ActivityService {
 private final MessageService messageService;
 @Autowired
 public ActivityServiceImpl(
 MessageService messageService
 ) {
 this.messageService = messageService;
 }
 @Override
 public void sendMessage(final String phone, final String content) {
 // ignore
 try {
 JSONObject sendResult = messageService.sendSingleMessage(phone, content);
 } catch (AliApiServerException e) {
 // ignore
 }
 }
}


The advantage of this is that it is a way to untie  ActivityService  and  AliApiService  Direct coupling of , Become an indirect coupling , By introducing  MessageService  The operation of such an intermediate layer , Does the code look a little better . Another key point is that you can start asynchronous processing , stay  MessageService  Can pass  @Async  Asynchronous annotation for asynchronous .

3） With the help of the event publishing mechanism

The above mode 2 solves the direct coupling of mode 1 , And the asynchronous processing mechanism can be introduced , Of course it's good , But it can be better , For example, take down this layer of indirect coupling , How do you do it? , If it's a single machine , You can consider  Spring  Release event mechanism of .

• Customize a  MessageSendEvent

/**
 * MessageSendEvent
 *
 * @author AFlymamba
 */
@Getter
public class MessageSendEvent extends ApplicationEvent {
 private static final long serialVersionUID = 6456904953414622941L;
 
 private JSONObject messageData;
 
 public MessageSendEvent(final Object source, final JSONObject messageData) {
 super(source);
 this.messageData = messageData;
 }
}


Event  Class holds a  JSONObject  Properties of , Better still, of course not  k-v  This kind of pointing to an object of ambiguous type , This is just a picture show .

• modify  activityServiceImpl  Add event publishing logic

@Slf4j
@Service
public class ActivityServiceImpl implements ActivityService {
 private final ApplicationContext applicationContext;
 @Autowired
 public ActivityServiceImpl(
 ApplicationContext applicationContext
 ) {
 this.applicationContext = applicationContext;
 }
 @Override
 public void sendMessage(final String phone, final String content) {
 // ignore
 JSONObject messageData = JSONUtil.createObj().putOnce("phone", phone).putOnce("content", content);
 MessageSendEvent messageSendEvent = new MessageSendEvent(this, messageData);
 applicationContext.publishEvent(messageSendEvent);
 }
}


It's obvious that , We have decoupled the business call point from the third-party code, which is relatively clean , utilize  Spring  Of  publish-event  Mechanism , This part is producer logic .

• Consumer logic

@EventListener
public void consumeMessage(final MessageSendEvent messageSendEvent) {
 // ignore
 try {
 JSONObject messageData = messageSendEvent.getMessageData();
 JSONObject sendResult = aliApiServerService.sendSingleMessage(messageData.getStr("phone"), messageData.getStr("content"));
 } catch (AliApiServerException e) {
 // ignore
 }
}


Depending on the  @EventListener  Annotations to enable consumers , adopt  event  Relevant business data can be obtained , Then follow the next logic , Be careful , This type of approach also supports asynchronous .

4） Open your brain

Is it OK to evolve to the third one ？ Please note that , The previous code here is based on a single machine , What if there are multiple machines ？ Is this kind of mechanism still applicable ？ For the producer consumer model , How idempotent does ？ Is the expansion easy to handle ？ A lot of questions are waiting .

Of course? , Naturally, there are many other excellent solutions and technologies , Professional  Message Queue、 Thread pool, etc , It depends on whether you are interested in continuing to play below , Long orange invites you to continue your exploration .

3、 ... and 、 It is recommended to write some reasons for docking with third-party code

This code looks simple , But there are many technical points worth referring to in detail , For example, the cache processing mechanism 、 Exception handling mechanism 、 Business and third-party interaction logic, etc , It is still worth practicing this code ability in depth .

Cache handling ：

What is this business mainly used for ？ Cache each other  api  Access credentials for the interface , However, if the two-way signature verification method is adopted, it is not applicable , But what can be cached ？ Cache the related configuration of the third party , As for local cache or distributed cache , It depends on the specific business .

Exception handling mechanism ：

The principle followed is actually 『  The principle of not trusting any third party should be maintained  』, You can see this in many classic books , The simplest third-party timeout leads to business execution failure , Through exception capture and transformation , Make the business clearer .

Third party interaction logic ：

This piece dabbles in  Http  Tools 、 encryption ,Apache  Of  HttpClient、Hutool  Of  HttpRequest、Spring  Provided  RestTemplate  Tools such as , Symmetric or asymmetric encryption and decryption 、 A one-way  hash  Related algorithms 、Base64、Md5  Equal coding ,url encode  operation , It's not hard to learn , But you have to be interested .

The above three categories are all code details , Look up , Business and third parties  api  Interactive mode , asynchronous 、 Release events 、 Introduce relevant design patterns such as strategies , These are higher level designs , Only thinking can be interested in practicing .

Four 、 summary

I'm orange , One  Java  The engineer , The above is my technical precipitation and thinking about docking with the third party , Sink down to understand the relevant thinking , I guess you should be very easy to win a third party , If you feel you have something to gain , Thank you for your kind words 、 Comment on 、 forward 、 Direct messages .