Lors de la conception d’interfaces API, faites attention à ces endroits !

Cet article vous apporte des connaissances pertinentes sur les API. Il présente principalement à quoi faut-il prêter attention lors de la conception d'API ? Pour ceux qui souhaitent concevoir une interface API élégante, jetons un coup d’œil ci-dessous. J’espère que cela sera utile à tout le monde.

Avant-propos

Dans le travail réel, nous devons souvent traiter avec des plates-formes tierces et pouvons nous connecter à des interfaces API de plates-formes tierces, ou fournir des interfaces API pour les appels de plates-formes tierces.

Alors la question est : si vous concevez une interface API élégante, peut-elle répondre aux besoins de : sécurité, appels répétables, stabilité, bon positionnement, etc. ?

Aujourd'hui, je vais vous parler de certaines choses auxquelles vous devez faire attention lors de la conception d'interfaces API. J'espère que cela vous sera utile.

1. Signature

Afin d'éviter que les données de l'interface API ne soient falsifiées, nous devons souvent signer l'interface API. 签名。

接口请求方将请求参数 + 时间戳 + 密钥拼接成一个字符串，然后通过md5等hash算法，生成一个前面sign。

然后在请求参数或者请求头中，增加sign参数，传递给API接口。

API接口的网关服务，获取到该sign值，然后用相同的请求参数 + 时间戳 + 密钥拼接成一个字符串，用相同的m5算法生成另外一个sign，对比两个sign值是否相等。

如果两个sign相等，则认为是有效请求，API接口的网关服务会将给请求转发给相应的业务系统。

如果两个sign不相等，则API接口的网关服务会直接返回签名错误。

问题来了：签名中为什么要加时间戳？

答：为了安全性考虑，防止同一次请求被反复利用，增加了密钥没破解的可能性，我们必须要对每次请求都设置一个合理的过期时间，比如：15分钟。

这样一次请求，在15分钟之内是有效的，超过15分钟，API接口的网关服务会返回超过有效期的异常提示。

目前生成签名中的密钥有两种形式：

一种是双方约定一个固定值privateKey。

另一种是API接口提供方给出AK/SK两个值，双方约定用SK作为签名中的密钥。AK接口调用方作为header中的accessKey传递给API接口提供方，这样API接口提供方可以根据AK获取到SK，而生成新的sgin。

2. 加密

有些时候，我们的API接口直接传递的非常重要的数据，比如：用户的银行卡号、转账金额、用户身份证等，如果将这些参数，直接明文，暴露到公网上是非常危险的事情。

由此，我们需要对数据进行加密。

目前使用比较多的是用BASE64加解密。

我们可以将所有的数据，安装一定的规律拼接成一个大的字符串，然后在加一个密钥，拼接到一起。

然后使用JDK1.8之后的Base64工具类处理，效果如下：

【加密前的数据】www.baidu.com
【加密后的数据】d3d3LmJhaWR1LmNvbQ==复制代码

为了安全性，使用Base64可以加密多次。

API接口的调用方在传递参数时，body中只有一个参数data，它就是base64之后的加密数据。

API接口的网关服务，在接收到data数据后，根据双方事先预定的密钥、加密算法、加密次数等，进行解密，并且反序列化出参数数据。

3. ip白名单

为了进一步加强API接口的安全性，防止接口的签名或者加密被破解了，攻击者可以在自己的服务器上请求该接口。

需求限制请求ip，增加ip白名单。

只有在白名单中的ip地址，才能成功请求API接口，否则直接返回无访问权限。

ip白名单也可以加在API网关服务上。

但也要防止公司的内部应用服务器被攻破，这种情况也可以从内部服务器上发起API接口的请求。

这时候就需要增加web防火墙了，比如：ModSecurity等。

4. 限流

如果你的API接口被第三方平台调用了，这就意味着着，调用频率是没法控制的。

第三方平台调用你的API接口时，如果并发量一下子太高，可能会导致你的API服务不可用，接口直接挂掉。

由此，必须要对API接口做限流。

限流方法有三种：

• 对请求ip做限流：比如同一个ip，在一分钟内，对API接口总的请求次数，不能超过10000次。

• 对请求接口做限流：比如同一个ip，在一分钟内，对指定的API接口，请求次数不能超过2000次。

• 对请求用户做限流：比如同一个AK/SK用户

  Le demandeur d'interface concatène les paramètres de requête + timestamp + clé en une chaîne, puis transmet md5 Attendre l'algorithme de hachage pour générer un signe précédent. 🎜🎜Ajoutez ensuite le paramètre sign au paramètre de requête ou à l'en-tête de requête et transmettez-le à l'interface API. 🎜🎜Le service de passerelle de l'interface API obtient la valeur du signe, puis utilise les mêmes paramètres de requête + horodatage + clé pour la fusionner en une chaîne, utilise le même algorithme m5 pour générer un autre signe et compare les deux valeurs de signe à voir s'ils sont égaux. 🎜🎜Si les deux signes sont égaux, cela est considéré comme une demande valide, et le service passerelle de l'interface API transmettra la demande au système métier correspondant. 🎜🎜Si les deux signes ne sont pas égaux, le service passerelle de l'interface API retournera directement une erreur de signature. 🎜🎜La question est : pourquoi faut-il ajouter un horodatage à la signature ? 🎜🎜Réponse : Pour des raisons de sécurité, afin d'éviter que la même demande soit utilisée à plusieurs reprises et d'augmenter la possibilité que la clé ne soit pas piratée, nous devons fixer un délai d'expiration raisonnable pour chaque demande, par exemple 15 minutes. 🎜🎜 Une telle demande est valable dans les 15 minutes. Si elle dépasse 15 minutes, le service passerelle de l'interface API renverra une invite d'exception indiquant que la période de validité a expiré. 🎜🎜Il existe actuellement deux formes de clés utilisées pour générer des signatures : 🎜🎜La première est que les deux parties s'accordent sur une clé privée à valeur fixe. 🎜🎜L'autre est que le fournisseur d'interface API donne deux valeurs ​​AK/SK, et les deux parties conviennent d'utiliser SK comme clé dans la signature. L'appelant de l'interface AK le transmet au fournisseur d'interface API en tant que accessKey dans l'en-tête, afin que le fournisseur d'interface API puisse obtenir le SK basé sur l'AK et générer un nouveau sgin. 🎜

  2. Chiffrement🎜🎜Parfois, notre interface API transmet directement des données très importantes, telles que : le numéro de carte bancaire de l'utilisateur, le montant du virement, la carte d'identité de l'utilisateur, etc., si c'est le cas. très dangereux d'exposer ces paramètres directement en texte clair au réseau public. 🎜🎜Ainsi, nous devons crypter les données. 🎜🎜Actuellement, BASE64 est utilisé pour le cryptage et le déchiffrement. 🎜🎜Nous pouvons regrouper toutes les données en une grande chaîne selon certaines règles, puis ajouter une clé pour les assembler. 🎜🎜Utilisez ensuite la classe d'outils Base64 après JDK1.8 pour le traitement. L'effet est le suivant : 🎜

  {    
  "code":0,    
  "message":null,    
  "data":[{"id":123,"name":"abc"}]
  },

  🎜Pour la sécurité, Base64 peut être utilisé pour chiffrer plusieurs fois. 🎜🎜Lorsque l'appelant de l'interface API transmet des paramètres, il n'y a qu'une seule donnée de paramètre dans le corps, qui sont les données cryptées après base64. 🎜🎜Le service passerelle de l'interface API, après avoir reçu les données, les déchiffre selon la clé, l'algorithme de cryptage, les temps de cryptage, etc. prédéterminés par les deux parties, et désérialise les données de paramètres. 🎜

  3. Liste blanche IP🎜🎜Afin de renforcer encore la sécurité de l'interface API et d'éviter que la signature ou le cryptage de l'interface ne soit piraté, l'attaquant peut demander l'interface sur son propre serveur. 🎜🎜Demande de limite de demande ip, ajoutez une liste blanche d'ip. 🎜🎜Seules les adresses IP de la liste blanche peuvent demander avec succès l'interface API, sinon elle ne renverra directement aucun droit d'accès. 🎜🎜La liste blanche IP peut également être ajoutée au service de passerelle API. 🎜🎜Mais il faut aussi éviter que le serveur d'applications interne de l'entreprise ne soit piraté. Dans ce cas, les requêtes d'interface API peuvent également être initiées depuis le serveur interne. 🎜🎜À ce stade, vous devez ajouter un pare-feu Web, tel que ModSecurity, etc. 🎜

  4. Limitation de courant 🎜🎜Si votre interface API est appelée par une plateforme tierce, cela signifie que la fréquence des appels ne peut pas être contrôlée. 🎜🎜Lorsqu'une plateforme tierce appelle votre interface API, si la simultanéité est trop élevée, votre service API peut devenir indisponible et l'interface raccrochera directement. 🎜🎜Il est donc nécessaire de limiter actuellement l'interface API. 🎜🎜Il existe trois méthodes de limitation de courant : 🎜

  • 🎜Limite le courant de l'IP demandée : Par exemple, la même IP, dans la minute, API Le nombre total de requêtes pour l'interface ne peut pas dépasser 10 000 fois. 🎜
  • 🎜Limiter le flux des interfaces de requêtes : Par exemple, pour la même IP, en une minute, le nombre de requêtes vers l'interface API spécifiée ne peut pas dépasser 2 000 fois. 🎜
  • 🎜Limiter le flux d'utilisateurs demandeurs : par exemple, le même utilisateur AK/SK ne peut pas effectuer plus de 10 000 requêtes à l'interface API en une minute. 🎜

  我们在实际工作中，可以通过nginx，redis或者gateway实现限流的功能。

  5. 参数校验

  我们需要对API接口做参数校验，比如：校验必填字段是否为空，校验字段类型，校验字段长度，校验枚举值等等。

  这样做可以拦截一些无效的请求。

  比如在新增数据时，字段长度超过了数据字段的最大长度，数据库会直接报错。

  但这种异常的请求，我们完全可以在API接口的前期进行识别，没有必要走到数据库保存数据那一步，浪费系统资源。

  有些金额字段，本来是正数，但如果用户传入了负数，万一接口没做校验，可能会导致一些没必要的损失。

  还有些状态字段，如果不做校验，用户如果传入了系统中不存在的枚举值，就会导致保存的数据异常。

  由此可见，做参数校验是非常有必要的。

  在Java中校验数据使用最多的是hiberate的Validator框架，它里面包含了@Null、@NotEmpty、@Size、@Max、@Min等注解。

  用它们校验数据非常方便。

  当然有些日期字段和枚举字段，可能需要通过自定义注解的方式实现参数校验。

  6. 统一返回值

  我之前调用过别人的API接口，正常返回数据是一种json格式，比如：

  {    
  "code":0,    
  "message":null,    
  "data":[{"id":123,"name":"abc"}]
  },

  签名错误返回的json格式：

  {    
  "code":1001,    
  "message":"签名错误",    
  "data":null
  }

  没有数据权限返回的json格式：

  {
      "rt":10,
      "errorMgt":"没有权限",
      "result":null
      }

  这种是比较坑的做法，返回值中有多种不同格式的返回数据，这样会导致对接方很难理解。

  出现这种情况，可能是API网关定义了一直返回值结构，业务系统定义了另外一种返回值结构。如果是网关异常，则返回网关定义的返回值结构，如果是业务系统异常，则返回业务系统的返回值结构。

  但这样会导致API接口出现不同的异常时，返回不同的返回值结构，非常不利于接口的维护。

  其实这个问题我们可以在设计API网关时解决。

  业务系统在出现异常时，抛出业务异常的RuntimeException，其中有个message字段定义异常信息。

  所有的API接口都必须经过API网关，API网关捕获该业务异常，然后转换成统一的异常结构返回，这样能统一返回值结构。

  7. 统一封装异常

  我们的API接口需要对异常进行统一处理。

  不知道你有没有遇到过这种场景：有时候在API接口中，需要访问数据库，但表不存在，或者sql语句异常，就会直接把sql信息在API接口中直接返回。

  返回值中包含了异常堆栈信息、数据库信息、错误代码和行数等信息。

  如果直接把这些内容暴露给第三方平台，是很危险的事情。

  有些不法分子，利用接口返回值中的这些信息，有可能会进行sql注入或者直接脱库，而对我们系统造成一定的损失。

  因此非常有必要对API接口中的异常做统一处理，把异常转换成这样：

  {    
  "code":500,    
  "message":"服务器内部错误",    
  "data":null
  }

  返回码code是500，返回信息message是服务器内部异常。

  这样第三方平台就知道是API接口出现了内部问题，但不知道具体原因，他们可以找我们排查问题。

  我们可以在内部的日志文件中，把堆栈信息、数据库信息、错误代码行数等信息，打印出来。

  我们可以在gateway中对异常进行拦截，做统一封装，然后给第三方平台的是处理后没有敏感信息的错误信息。

  8. 请求日志

  在第三方平台请求你的API接口时，接口的请求日志非常重要，通过它可以快速的分析和定位问题。

  我们需要把API接口的请求url、请求参数、请求头、请求方式、响应数据和响应时间等，记录到日志文件中。

  最好有traceId，可以通过它串联整个请求的日志，过滤多余的日志。

  当然有些时候，请求日志不光是你们公司开发人员需要查看，第三方平台的用户也需要能查看接口的请求日志。

  这时就需要把日志落地到数据库，比如：mongodb或者elastic search，然后做一个UI页面，给第三方平台的用户开通查看权限。这样他们就能在外网查看请求日志了，他们自己也能定位一部分问题。

  9. Conception idempotente

  La plateforme tierce est très susceptible de demander notre interface plusieurs fois dans un laps de temps très court, par exemple : deux fois en 1 seconde. Il se peut qu'il y ait un bug dans leur système d'entreprise, ou que l'appel d'interface échoue et soit réessayé, notre interface API doit donc être idempotente. 幂等设计。

  也就是说要支持在极短的时间内，第三方平台用相同的参数请求API接口多次，第一次请求数据库会新增数据，但第二次请求以后就不会新增数据，但也会返回成功。

  这样做的目的是不会产生错误数据。

  我们在日常工作中，可以通过在数据库中增加唯一索引，或者在redis保存requestId和请求参来保证接口幂等性。

  对接口幂等性感兴趣的小伙伴，可以看看我的另一篇文章《高并发下如何保证接口的幂等性？》，里面有非常详细的介绍。

  10. 限制记录条数

  对于对我提供的批量接口，一定要限制请求的记录条数。

  如果请求的数据太多，很容易造成API接口超时等问题，让API接口变得不稳定。

  通常情况下，建议一次请求中的参数，最多支持传入500条记录。

  如果用户传入多余500条记录，则接口直接给出提示。

  建议这个参数做成可配置的，并且要事先跟第三方平台协商好，避免上线后产生不必要的问题。

  11. 压测

  上线前我们务必要对API接口做一下压力测试，知道各个接口的qps情况。

  以便于我们能够更好的预估，需要部署多少服务器节点，对于API接口的稳定性至关重要。

  之前虽说对API接口做了限流，但是实际上API接口是否能够达到限制的阀值，这是一个问号，如果不做压力测试，是有很大风险的。

  比如：你API接口限流1秒只允许50次请求，但实际API接口只能处理30次请求，这样你的API接口也会处理不过来。

  我们在工作中可以用jmeter或者apache benc对API接口做压力测试。

  12. 异步处理

  一般的API接口的逻辑都是同步处理的，请求完之后立刻返回结果。

  但有时候，我们的API接口里面的业务逻辑非常复杂，特别是有些批量接口，如果同步处理业务，耗时会非常长。

  这种情况下，为了提升API接口的性能，我们可以改成异步处理。

  在API接口中可以发送一条mq消息，然后直接返回成功。之后，有个专门的mq消费者去异步消费该消息，做业务逻辑处理。

  直接异步处理的接口，第三方平台有两种方式获取到。

  第一种方式是：我们回调第三方平台的接口，告知他们API接口的处理结果，很多支付接口就是这么玩的。

  第二种方式是：第三方平台通过轮询调用我们另外一个查询状态的API接口，每隔一段时间查询一次状态，传入的参数是之前的那个API接口中的id集合。

  13. 数据脱敏

  有时候第三方平台调用我们API接口时，获取的数据中有一部分是敏感数据，比如：用户手机号、银行卡号等等。

  这样信息如果通过API接口直接保留到外网，是非常不安全的，很容易造成用户隐私数据泄露的问题。

  这就需要对部分数据做数据脱敏了。

  我们可以在返回的数据中，部分内容用星号代替。

  已用户手机号为例：182****887

  C'est-à-dire qu'il est nécessaire de prendre en charge la plateforme tierce pour demander l'interface API plusieurs fois avec les mêmes paramètres dans un laps de temps très court. La première fois que la base de données est demandée, de nouvelles données seront ajoutées, mais après la deuxième requête, aucune nouvelle donnée ne sera ajoutée. Mais cela renverra également un succès.
  Le but est de ne pas générer de données erronées.
  Dans notre travail quotidien, nous pouvons ajouter un index unique à une base de données, ou enregistrer requestId dans redis et demander paramètres pour garantir l’idempotence de l’interface.
  Les amis intéressés par l'idempotence de l'interface peuvent lire mon autre article "Comment garantir l'idempotence des interfaces sous haute concurrence ? ", qui possède une introduction très détaillée.

  10. Limiter le nombre d'enregistrements

  Pour l'interface batch qui m'a été fournie, veillez à limiter le nombre d'enregistrements demandés.

  • Si trop de données sont demandées, il est facile de provoquer un délai d'expiration de l'interface de l'API et d'autres problèmes, rendant l'interface de l'API instable.

  Normalement, il est recommandé que les paramètres d'une requête prennent en charge jusqu'à 500 enregistrements.

  • Si l'utilisateur saisit plus de 500 enregistrements, l'interface affichera directement une invite.

  Il est recommandé que ce paramètre soit rendu configurable et négocié à l'avance avec la plateforme tierce pour éviter des problèmes inutiles après la mise en ligne.

  • 11. Stress test

    Avant de se connecter, il faut faire un stress test sur l'interface API pour connaître le qps de chaque interface >Situation.
  • Afin que nous puissions mieux estimer le nombre de nœuds de serveur à déployer, ce qui est crucial pour la stabilité de l'interface API.
    Bien que l'interface API ait été limitée en termes de flux de courant auparavant, il s'agit en fait d'un point d'interrogation quant à savoir si l'interface API peut atteindre le seuil limite. Si aucun test de résistance n'est effectué, le risque est grand.
  • Par exemple : votre interface API a une limite actuelle de seulement 50 requêtes par seconde, mais l'interface API réelle ne peut gérer que 30 requêtes, votre interface API ne pourra donc pas la gérer.
    Nous pouvons utiliser jmeter ou apache benc pour effectuer des tests de résistance sur l'interface API au travail.

  12. Traitement asynchrone

  • La logique générale de l'interface API est traitée de manière synchrone et le résultat est renvoyé immédiatement une fois la demande terminée.

  Mais parfois, la logique métier de nos interfaces API est très complexe, en particulier certaines interfaces batch si les affaires sont traitées de manière synchrone, cela prendra très longtemps.

  • Dans ce cas, afin d'améliorer les performances de l'interface API, nous pouvons la changer en traitement asynchrone.

    🎜Dans l'interface API, vous pouvez envoyer un message mq puis renvoyer directement le succès. Après cela, il existe un consommateur mq dédié pour consommer le message de manière asynchrone et effectuer le traitement de la logique métier. 🎜🎜La plateforme tierce peut obtenir l'interface de traitement asynchrone directe de deux manières. 🎜🎜La première façon est la suivante : nous rappelons l'interface de la plateforme tierce pour les informer des résultats du traitement de l'interface API. C'est ainsi que fonctionnent de nombreuses interfaces de paiement. 🎜🎜La deuxième méthode est la suivante : la plate-forme tierce appelle notre autre interface API pour interroger l'état via Polling et interroge l'état de temps en temps. Les paramètres transmis proviennent de l'interface API précédente. .collecte d'identité. 🎜

    13. Désensibilisation des données🎜🎜Parfois lorsqu'une plateforme tierce appelle notre interface API, une partie des données obtenues sont des données sensibles, comme le numéro de téléphone portable de l'utilisateur, le numéro de carte bancaire. , etc. attendez. 🎜🎜Si de telles informations sont directement conservées sur le réseau externe via l'interface API, elles sont très dangereuses et peuvent facilement conduire à une fuite des données confidentielles des utilisateurs. 🎜🎜Cela nécessite une désensibilisation des données pour certaines données. 🎜🎜Nous pouvons remplacer une partie du contenu par des astérisques dans les données renvoyées. 🎜🎜Prenons comme exemple le numéro de téléphone portable de l'utilisateur : 182****887. 🎜🎜De cette façon, même si les données sont divulguées, seule une partie d'entre elles sera divulguée et il sera inutile pour les criminels d'obtenir ces données. 🎜🎜14. Document d'interface complet🎜🎜Pour être honnête, un document d'interface API complet peut réduire considérablement les coûts de communication et éviter à l'autre partie de faire de nombreux détours lorsque les deux parties effectuent l'amarrage de l'interface. 🎜🎜Les informations suivantes doivent être incluses dans le document d'interface : 🎜🎜🎜🎜Adresse de l'interface 🎜🎜🎜🎜Méthode de demande, telle que : post ou get Code de retour et message d'erreur🎜🎜🎜🎜Exemple de cryptage ou de signature🎜🎜🎜🎜 Démo complète de la demande🎜

  • Instructions supplémentaires, telles que : ouvrir une liste blanche d'adresses IP.

  Il est préférable d'unifier le style de dénomination des noms d'interface et de champ dans le document d'interface, par exemple, utilisez 驼峰标识 pour les nommer.

  Unifiez le type et la longueur des champs, par exemple : le champ id utilise le type Long et la longueur est spécifiée à 20. Le champ d'état utilise le type int, avec une longueur fixe de 2, etc.

  Champs de format d'heure uniforme, par exemple : l'heure utilise le type String, le format est : aaaa-MM-jj HH:mm:ss.

  Indiquez AK/SK et le nom de domaine dans le document d'interface, demandez à quelqu'un de le fournir séparément, etc.

  Apprentissage recommandé : "Tutoriel vidéo PHP"
  

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!