接口文档分析手册

接口文档分析手册包括明确使用对象：开发&测试人员、名词/术语解释、需求文档结构、分析维度（偏技术性）几个部分。

接口文档分析手册

• 明确使用对象：开发&测试人员
  • What they concern?
    • 参数定义是否清晰
    • 参数格式是否提供
    • 加解密方式
    • 参数字段是否强制
    • 是否需要白名单IP地址
      • If Yes：所有沙盒API接口的请求都需要提前联系渠道基础设施团队申请将IP地址加入白名单；否则无法进行调试和集成
      • PalmPay IP
        • TEST: 218.17.161.141
        • LIVE: 34.241.26.138
• 名词/术语解释
  • API：Application Programming Interface 应用程序编程接口
    • Niko白话：就是预先被设定好的应用程序，规定好了和外部软件或应用组织间的交互形式。
  • Method 请求方法
    • GET：一般用于查询数据
    • POST：一般用于添加
    • PUT：一般用于修改，完整替换
    • DELETE：一般用于删除操作
    • PATCH：一般用于修改操作，局部修改
  • 加密方式（偏技术性，可跳过）
    • 非对称加密（更慢）：RSA（最常见）；DSA
    • 对称加密（更快）：DES；AES
    • Hash 哈希算法：SHA-1；SHA-2；MD5
      • Niko白话：将目标文本转换成长度相同且不可逆的杂凑字符串；严格上来说并不属于加密算法, 是与加密算法属于并列关系的一种算法。但是可以发挥加密算法相同的隐私性作用。
      • 作用：无需借助任何秘钥即可对信息进行加密；
      • 特点：单项不可逆，可重复，输出长度固定
      • 常用于：一次性密码存储，信息完整性校验
  • Callback 回调
    • Niko白话：埋下开关，等待对象自己触发；执行函数时，采用不阻塞的方式，继续程序，当函数执行完毕，再返回来返回结果（常用于异步场景，还能解决单线程执行效率的问题，因为将调用者和被调用者分开了）
  • 调试 vs 集成：调试是集成的前置环节
    • Debug 调试：将接口调通
    • Integration 集成：将调通的接口集成到内部系统
  • IP Whitelisting
    • 接口对于安全性有一定的要求，通常渠道会为了减少非法请求，采用ip白名单设计，只允许部分许可ip访问系统。
  • Authorization 认证
    • Niko白话：可以看作是通行令牌，一般会给一串id或API key
  • Test Credentials & Live Credentials 测试&生产密钥
• 需求文档结构
  • 修订记录
    • 版本号；修改日期；撰写人；评审人员；批准；修改内容
  • 需求背景
    • 渠道简介，业务地区，计费币种，业务类型
  • 接口清单
  • 接口明细
    • 结构
      • 接口URL：Path路径
      • 请求头 Http Request Header
        • Method 请求方法
        • Content-Type 内容形式：application/json；application/xml
      • 请求体 Request Body
      • 响应体 Response Body
    • 参数内容
      • 强制性 M/O
        • M：Mandatory 必传字段
        • O：Optional 选传字段
      • 字段描述 Description
        • 注意事项：需要抽象且具象化转译为技术能看懂的语言，从业务理解及产品角度进行转述
      • 格式 Format
        • 字符串 string
        • 整数 int
        • 小数 decimal
        • 布尔值 bool
        • 日期 DateTime
      • 示例 Example：强烈建议附上
    • markdown插入代码块
  • 渠道报文日志：要会看渠道报文日志，尽量能自己使用kibana
  • 交易订单状态映射 status mapping
    • 目的：将渠道定义状态与PP定义的交易状态进行映射
  • 响应码说明
    • 目的：以助于分析接口反应结果，排查异常原因，准确定位问题。
    • 类型：需辨别是否通用码或渠道自定义状态码
      • 渠道响应码说明 response code list
      • 渠道错误码说明 error code list
      • 通用http响应码 HTTP Status Code
        • 常见http code
          • 200 - OK
          • 100 - Continue
          • 400 - Bad Request
          • 401 - Unauthorized
          • 403 - Forbidden
• 分析维度（偏技术性）
  • 功能维度
    • 针对单个功能
    • 针对业务场景：针对业务流程开展接口测试；按接口的调用顺序开展测试。
  • 性能维度
    • 接口响应时间
      • 客户端发出请求到服务器回发响应的时长
    • TPS 吞吐量
      • 单位时间事物数，如1秒内接口所能处理的请求数量
    • QPS 每秒查询率
      • 一台服务器每秒能够响应的查询次数
    • 并发
      • 同一时间，同时向服务器的接口发送请求，所能正确处理的数量
      • 并发 = qps*接口响应时间
    • CPU 服务器资源利用率：衡量性能
  • 安全性维度
    • 敏感数据加密，如密码、银行卡号等
    • SQL注入：在输入框写入SQL语句，测试是否能得到数据库的查询结果