EWS SyncFolderItems SyncState正确报ErrorInvalidSyncStateData方案

问题背景 #

• 调用Microsoft EWS API的SyncFolderItems操作拉取邮件变更数据，多次成功调用后接口返回ErrorInvalidSyncStateData错误
• 传入请求的SyncState参数直接取自上一次成功调用的响应结果，传参逻辑本身符合接口要求
• 返回的错误响应内容如下：

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <t:ServerVersionInfo MajorVersion="8" MinorVersion="0" 
                         MajorBuildNumber="628" MinorBuildNumber="0" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <SyncFolderItemsResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                             xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                             xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <m:ResponseMessages>
        <m:SyncFolderItemsResponseMessage ResponseClass="Error">
          <m:MessageText>Synchronization state data is corrupt or otherwise invalid.</m:MessageText>
          <m:ResponseCode>ErrorInvalidSyncStateData</m:ResponseCode>
          <m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
          <m:SyncState />
          <m:IncludesLastItemInRange>true</m:IncludesLastItemInRange>
        </m:SyncFolderItemsResponseMessage>
      </m:ResponseMessages>
    </SyncFolderItemsResponse>
  </soap:Body>
</soap:Envelope>

• 原有处理逻辑是遇到该错误就清空本地所有邮件存储，从空SyncState开始重新全量同步，需要更优的错误处理方案。

优化处理方案 #

遇到这个错误不用直接清空本地数据全量重刷，按以下逻辑处理可以把影响降到最低：

• 先排查SyncState传参损坏问题
  这个错误80%以上的偶发场景都是SyncState在本地存储或请求构造环节被损坏。SyncState是base64格式的二进制状态值，如果你在存储到数据库、缓存，或者构造XML请求的时候做了多余的转义、字符集转换，很容易出现值不匹配的问题。遇到报错先拿本地存储的SyncState和上次接口返回的原始返回值逐字符比对，确认没有多字符、少字符、转义错误的问题，先排除低级错误。
• 保留多版本历史SyncState做回退重试
  不要只存最后一次同步成功的SyncState，本地维护一个长度为3-5的SyncState版本队列，每次同步成功就把最新的SyncState入队，淘汰最旧的版本。遇到当前SyncState报错时，按从新到旧的顺序依次用历史SyncState重试增量同步，只要有一个版本调用成功，就可以从对应断点继续拉取变更，完全不需要全量重刷。

  注意：回退到旧版SyncState只会导致部分已同步过的变更重复返回，本地通过邮件唯一ItemId做去重即可，不会出现数据遗漏。

• 全量重同步时不要提前清空本地数据
  如果所有历史SyncState都失效（比如服务端过期、邮箱迁移导致状态失效），也不需要先清空本地所有邮件数据。传空SyncState发起全量拉取时，对拉取到的每一封邮件按ItemId匹配本地数据：本地已存在的就更新对应字段，不存在的直接新增；等全量拉取完成后，再把本地存在但本次全量列表中不存在的邮件标记为删除即可。这种方式不会出现同步过程中本地数据为空的问题，就算同步中途中断，也不会影响已有数据的正常使用。
• 针对老版本Exchange的前置规避
  从返回的服务端版本头看，对接的是Exchange 2007（MajorVersion=8），这个版本的SyncFolderItems接口本身有不少已知bug：单次拉取条目数不要设置超过500，尽量分页拉取；请求中只指定业务必需的最小属性集合，不要拉取冗余字段，能大幅降低这个错误的触发概率。另外这个版本的SyncState在服务端默认有效期是30天，如果同步任务停了超过1个月再重启，大概率会遇到状态失效，直接走上面的无清空全量同步逻辑即可。

内容的提问来源于stack exchange，提问作者Wen Hsiao