我發現了大廠OpenApi接口的bug！你發現了嗎？
本文記錄我在對接字節旗下產品火山云游戲OpenApi 接口文檔時遇到的坑，希望能幫助大家（火山云旗下云游戲產品的文檔坑很多，我算是從零到一都踩了一遍，特此記錄，希望大家引以為鑒）。
1. 文檔問題
很經典的開局一張圖，對接全靠問。
產品給的圖
這里給大家強調下，當要跟第三方產品對接時，一定要確認拿到的文檔是不是最新版本。
比如我在這次對接中，第一次拿到的文檔是產品給的，在業務中需要用到一個用戶主動退出游戲的接口，于是我在第一份文檔里面找到一個用戶退出游戲的接口 RomoveUser。
RemoveUser
但是當我在控制臺調用此接口報錯后，去群里一問才發現，對方建議我使用官網公布的最新接口文檔。
官網最新文檔：https://www.volcengine.com/docs/6512/143674
進入官網發現 RemoveUser 這個接口已經是歷史接口了，官方建議換到 BanRoomUser 接口。
BanRoomUser
OK，這里算是踩到了第一個坑，文檔版本不是最新。
ps：還要說一下，火山云旗下云游戲的這個 OpenApi 接口文檔需要在群里聯系他們開白才能看到，說實話給我的感覺很奇怪，懷疑產品是否有趕鴨子上架問題，暫且懷疑他們的目的是防止不明攻擊吧。
2. OpenApi 示例 demo
第三方接口的接入一般都需要做鑒權。火山云旗下云游戲產品的 OpenApi 接口接入當然也不例外。于是我開始了第二個踩坑之旅，那就是他們給出的 OpenApi 示例 demo 的使用過于簡單。
圖片
火山云旗下云游戲產品的 OpenApi 示例 demo 寫的很簡單，只提供了一個 GET 請求示例。
OpenApi 示例 demo 地址：https://github.com/volcengine/veGame
但是在我司的業務場景還是上個問題，需要一個用戶主動退出游戲的接口，在火山云官網的 OpenApi 文檔中我也找到了這個接口，就是上文提到的 BanRoomUser 接口。
但是在官方文檔中 BanRoomUser 接口是一個 POST JSON 格式的請求。官方給出的 OpenApi 示例 demo 中并沒有關于 POST JSON 請求的示例代碼，所以只能靠我一個人查看他們提供的 SDK 依賴源碼硬猜來寫...，這就很讓人頭痛了。
好在我翻閱他們 SDK 源碼中找到一個靠譜的 json(...) 請求方法，來完成這個 POST JSON 請求。
圖片
OK，說干就干，直接寫好示例代碼，開始發送 POST JSON 請求。
錯誤返回
what f**k？什么鬼，返回了我一個 null，此時我的內心中充滿了一個大大的問號。
我開始懷疑我的代碼是不是寫錯了。但是當我經歷過數次源碼 debug 以及調用其他 OpenApi 接口測試并得到正確返回后，我堅定的認為我沒錯，這就是火山云 OpenApi 的 bug！
正常返回
OK，說干就干，直接反饋給火山那邊。
接著火山那邊的人就聯系說下午兩點開會一起遠程共享我的屏幕看看，OK 欣然接收，讓他們見證下他們寫的 bug！
...
時間來到下午兩點，當我共享屏幕給字節工程師演示這個 bug 時，我的控制臺打印如下：
圖片
woca，竟然不是 null！好在我腦袋靈活，思路清晰，瞬間想到我改了一個參數 GameId，之前返回 null 時，我傳的 GameId 是一個假數據，現在我傳的是一個真數據。造成了返回不一致。
OK，找到了返回正常的原因，當我把 GameId 改成假數據時，如我所愿，返回了一個 null。
圖片
自此，我也就在字節工程師的圍觀下，復現了他們的 OpenApi 接口的線上 bug。大功告成。
3. 鑒權失敗
字節提供的 OpenApi 示例 demo 現在算是跑通了，但是由于我司項目一些依賴限制問題，我們不能直接引入火山云旗下云游戲產品的 SDK 依賴。所以我還得手動編寫生成簽名的代碼。于是我開始了第三個踩坑之旅，那就是 GET 請求驗簽成功 POST 請求驗簽失敗的問題。
這里先說一下，火山云提供了手動生成簽名的示例代碼：
圖片
Java 生成簽名的代碼：https://github.com/volcengine/volc-openapi-demos/blob/main/signature/java/Sign.java
這里我也是直接把簽名代碼拿來即用就行，一開始接入生成簽名代碼非常順利，GET 請求的 OpenApi 接口都是可以順利調通的，但是當我調用 BanRoomUser 接口時（沒錯，又是這個接口，踩的三個坑都與這個接口有關），直接提示驗簽失敗！
驗簽失敗
OK，開始排查為什么簽名失敗。
圖片
查看源碼發現，POST JSON 請求時的 contentType 還是 application/x-www-form-urlencoded，直覺告訴我這里不對，所以改成 application/json 試試，看看控制臺返回，
圖片
很好，還是驗簽失敗！！！
我盡力了兄弟們，這個坑踩的我是無話可說。直接聯系直接字節開發人員看下我的請求內容是哪里有問題。
在與字節開發人員一起觀摩我寫的代碼以及生成的簽名之后，大家都沒找到問題所在。那沒辦法了，只能上服務器看接口請求日志了。
圖片
大家可以看出問題在哪里嗎？沒錯我剛剛不是把 contentType 改成了 application/json 嗎，為什么日志顯示的 contentType 是 application/json; charset=utf-8！。
OK，到這里問題也找到了，原因是我這個項目用的 http 請求工具是 okhttp3。他自動給我拼接上去的！
那么怎么解決嘞，替換 http3 工具的話，改造成本比較大，所以我就順勢把代碼的 contentType 也改成application/json; charset=utf-8。
在測試一遍，看看控制臺打印。
圖片
OK，拿到成功響應，自此也就解決了第三個坑，POST JSON 請求時的驗簽不匹配問題。
最后給大家貼出手動生成驗簽的代碼，有需要自取。
@Slf4j
public class Sign {
private static final BitSet URLENCODER = new BitSet(256);
private static final String CONST_ENCODE = "0123456789ABCDEF";
public static final Charset UTF_8 = StandardCharsets.UTF_8;
private final String region;
private final String service;
private final String host;
private final String path;
private final String ak;
private final String sk;
static {
int i;
for (i = 97; i <= 122; ++i) {
URLENCODER.set(i);
}
for (i = 65; i <= 90; ++i) {
URLENCODER.set(i);
}
for (i = 48; i <= 57; ++i) {
URLENCODER.set(i);
}
URLENCODER.set('-');
URLENCODER.set('_');
URLENCODER.set('.');
URLENCODER.set('~');
}
public Sign(String region, String service, String host, String path, String ak, String sk) {
this.region = region;
this.service = service;
this.host = host;
this.path = path;
this.ak = ak;
this.sk = sk;
}
public Headers calcAuthorization(String method, Map<String, String> queryList, byte[] body,
Date date, String action, String version) throws Exception {
// 請求頭
Map<String, String> headerMap = new HashMap<>();
String contentType = "application/x-www-form-urlencoded; charset=utf-8";
if (body == null) {
body = new byte[0];
} else {
contentType = "application/json; charset=utf-8";
}
String xContentSha256 = hashSHA256(body);
SimpleDateFormat sdf = new SimpleDateFormat("yyyyMMdd'T'HHmmss'Z'");
sdf.setTimeZone(TimeZone.getTimeZone("GMT"));
// String xDate = "20240515T061353Z";
String xDate = sdf.format(date);
String shortXDate = xDate.substring(0, 8);
String signHeader = "content-type;host;x-content-sha256;x-date";
SortedMap<String, String> realQueryList = new TreeMap<>(queryList);
realQueryList.put("Action", action);
realQueryList.put("Version", version);
StringBuilder querySB = new StringBuilder();
for (String key : realQueryList.keySet()) {
querySB.append(signStringEncoder(key)).append("=").append(signStringEncoder(realQueryList.get(key))).append("&");
}
querySB.deleteCharAt(querySB.length() - 1);
String canonicalStringBuilder = method + "\n" + path + "\n" + querySB + "\n" +
"content-type:" + contentType + "\n" +
"host:" + host + "\n" +
"x-content-sha256:" + xContentSha256 + "\n" +
"x-date:" + xDate + "\n" +
"\n" +
signHeader + "\n" +
xContentSha256;
// log.info("canonicalStringBuilder is {}", canonicalStringBuilder);
String hashcanonicalString = hashSHA256(canonicalStringBuilder.getBytes());
String credentialScope = shortXDate + "/" + region + "/" + service + "/request";
String signString = "HMAC-SHA256" + "\n" + xDate + "\n" + credentialScope + "\n" + hashcanonicalString;
// log.info("signString is {}", signString);
byte[] signKey = genSigningSecretKeyV4(sk, shortXDate, region, service);
String signature = HexUtil.encodeHexStr(hmacSHA256(signKey, signString));
String auth = "HMAC-SHA256" +
" Credential=" + ak + "/" + credentialScope +
", SignedHeaders=" + signHeader +
", Signature=" + signature;
headerMap.put("Authorization", auth);
headerMap.put("X-Date", xDate);
headerMap.put("X-Content-Sha256", xContentSha256);
headerMap.put("Host", host);
headerMap.put("Content-Type", contentType);
headerMap.put("User-Agent", "volc-sdk-java/v");
headerMap.put("Accept", "application/json");
return Headers.of(headerMap);
}
private static String signStringEncoder(String source) {
if (source == null) {
return null;
}
StringBuilder buf = new StringBuilder(source.length());
ByteBuffer bb = UTF_8.encode(source);
while (bb.hasRemaining()) {
int b = bb.get() & 255;
if (URLENCODER.get(b)) {
buf.append((char) b);
} else if (b == 32) {
buf.append("%20");
} else {
buf.append("%");
char hex1 = CONST_ENCODE.charAt(b >> 4);
char hex2 = CONST_ENCODE.charAt(b & 15);
buf.append(hex1);
buf.append(hex2);
}
}
return buf.toString();
}
public static String hashSHA256(byte[] content) throws Exception {
try {
MessageDigest md = MessageDigest.getInstance("SHA-256");
// return HexFormat.of().formatHex(md.digest(content));
return HexUtil.encodeHexStr(md.digest(content));
} catch (Exception e) {
throw new Exception(
"Unable to compute hash while signing request: "
+ e.getMessage(), e);
}
}
public static byte[] hmacSHA256(byte[] key, String content) throws Exception {
try {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(key, "HmacSHA256"));
return mac.doFinal(content.getBytes());
} catch (Exception e) {
throw new Exception(
"Unable to calculate a request signature: "
+ e.getMessage(), e);
}
}
private byte[] genSigningSecretKeyV4(String secretKey, String date, String region, String service) throws Exception {
byte[] kDate = hmacSHA256((secretKey).getBytes(), date);
byte[] kRegion = hmacSHA256(kDate, region);
byte[] kService = hmacSHA256(kRegion, service);
return hmacSHA256(kService, "request");
}
}總結
在與火山云旗下云游戲產品的 OpenApi 接口對接過程中，我總共踩了三個坑。一是文檔版本不是最新，二是官方提供的 OpenApi 示例 demo 過于簡單，三是官方提供的驗簽代碼沒有考慮到 POST JSON 請求場景下的 contentType 設置問題。
