概述

Dataphin数据服务支持在API调用的时候通过OrderByList进行结果的排序，通过指定不同的排序字段及排序方式，可快速完成需自定义所需的排序规则，而不需要重新创建新的接口。但是在创建API时，常常被忽略但是至关重要的是结果的默认排序。

目标受众

• API开发者
  
• API调用者（应用开发者）
  

版本要求

Dataphin 4.1及以上版本

为什么需要默认排序规则

1. 用户体验: 默认排序可以提供给调用方一个直观且易于理解的数据结果，减少应用开发者指定排序的设置。
   
2. 一致性: 在没有明确排序请求的情况下，应用一致的默认排序逻辑能确保每次调用API时返回的数据顺序相同，增加系统的可预测性。
   
3. 正确性：Dataphin数据服务API支持在调用时指定分页，通过分页查询获取全量的结果数据。但是在未指定排序保证结果数据的稳定排序时，数据库返回的结果有很大的概率是不一致的，导致多页拼装的结果是不正确的。比如第一次调用的结果为[1,2,3,4,5]，取第1页（2条数据）获得1和2，而第二次调用的结果为[1,3,2,4,5]，取第2页（2条数据）获得2和4。而客户的预期为3和4。指定排序可确保结果的正确性。
   

如何设定有效的默认排序规则

1. 确定核心字段
   

分析API的主要使用场景，确定哪些属性最能反映数据的重要程度或关联性。例如，在电商API中，商品的销售量、上架时间或评分可能是关键排序依据。

2. 选择排序逻辑
   

根据业务需求决定是采用升序（如日期由早到晚）还是降序（如热门程度从高到低）。通常，最新的或最受欢迎的内容会被置于前列。

3. 考虑多字段排序
   

当单一字段不足以区分数据重要性或确定唯一排序时，可以采用多字段排序。例如，先按发布时间降序，再按评论数降序，以平衡新旧内容的展示。

4. 处理空值和特殊值
   

明确定义如何处理缺失值或特殊值（如null值），避免这些记录在排序中导致不一致或异常。

5. 性能考量
   

评估所选排序字段对数据库查询性能的影响，减少不必要的排序设置。针对不同的数据源考虑使用创建索引进行查询加速，提升查询性能。

产品功能概览

设置API的默认排序规则

1）通过向导式的方式基于服务单元创建API时，可通过界面化的方式设置排序。

比如在分页查询客户列表时，可通过对最近购买时间字段做降序排序，再对customer_id升序排序，以确保符合大部分的业务场景，并确保分页查询时结果的正确性

1. 当使用SQL模式进行更加灵活的API定义时，在SQL代码中指定排序的方式，比如在MySQL中，使用order by指定排序的字段及排序方式
   

在API调用时，也可指定排序规则

在调用API时，我们还可以通过OrderByList的参数覆盖API配置的默认排序（特殊说明见排序优先级说明）。通过Dataphin数据服务提供的API测试功能、Postman等API调用工具或通过数据服务SDK可调用Dataphin已提交或已发布的API。以下的例子中我们用API测试功能进行说明。

1. 传入customer name的查询参数，OrderByList参数留空，则使用默认的排序
   

排序的结果为按Last_purchase_date倒序排序（由于这里没有相同的last purchase date，这里没有体现出来对customer_id的升序排序）

2. 修改OrderByList，根据customer id升序排序
   

查询的结果变更为按照customer ID升序排序，即覆盖了默认的配置。

排序优先级说明

为了兼容历史已经发布的API以及已经上线的调用的结果的一致性，我们新版本中针对直连数据源-SQL模式的基础SQL模式和服务单元API-SQL模式，增加了排序优先级的设置，可支持设置排序生效的优先级，可选择SQL脚本或OrderByList。

• SQL脚本：若SQL脚本中指定了排序，则公共请求参数中的OrderByList不生效
  
• OrderByList请求参数：SQL脚本及OrderByList公共请求参数同时生效，OrderByList公共请求参数有更高优先级
  

历史的API升级新版本后设置为SQL脚本，新增的API默认为OrderByList请求参数。

1. 若需要为已发布在使用中的API增加排序设置，请特别注意已存在调用的兼容性，与各个调用方进行排序规则的确认。

1. 若调用方已通过OrderByList指定排序，增加排序设置将使已有的OrderByList失效，需要将排序优先级设置修改为“OrderByList请求参数”，但是由于OrderByList和SQL的排序语句同时生效，需要调用方确认结果是否符合业务预期。
   
2. 若调用方未通过OrderByList指定排序，则增加排序设置后将修改默认的排序规则。
   

综上，当增加API排序设置时，建议修改排序优先级设置为“OrderByList请求参数”，但请与调用方进行业务的确认。

2. 若需删除已发布使用中的API的排序设置

1. 即使调用方已通过OrderByList指定排序，原本的API的SQL脚本中的排序也不生效，可安全的删除API的SQL脚本中的排序语句
   
2. 若调用方未通过OrderByList指定排序，原本的API的SQL脚本中的排序生效，删除API的SQL脚本中的排序语句后，结果的排序将变更，需要与调用方确认是否符合业务预期。
   

下表为不同的API的类型支持排序设置的情况，以及调用时的排序的生效优先级：

我们建议新增的API的排序优先级设置为“OrderByList请求参数”，可指定默认排序，也可以在调用时自定义排序规则，灵活性与易用性均可兼顾。当然排序本身也会有一定的资源和时间的成本，在设置排序字段时也需要谨慎的处理。

总结

API的排序设置是一个需要谨慎评估的过程，不仅要考虑业务诉求，调用的便利性，也要考虑API的性能。产品的配置中提供了更加丰富和灵活的配置简化了部分配置的过程，还需要持续与业务方进行沟通，避免API实际作用与预期不符，造成数据的错误的问题或者稳定性问题。