全局约定（一定要看）

成功判定

• status == 10000 表示业务成功；否则触发 onBizError(status, msg, traceId)。

TraceId

• 服务端返回 trace_id → SDK 字段 traceId。无论成功/失败，日志与排障务必带上该值。

坐标与单位（最易混淆）

• 请求坐标：始终为字符串 "lng,lat"（经度在前）。
• 返回坐标：两种形态 1）路径点（路线规划 results[].routes[].geo_list）：latitude / longitude； 2）文本坐标（公交/步行段、站点、origin/destination 等）：字符串 "lng,lat"。
• 距离：distance/dist → 米；时长：duration → 秒；费用：cost → 分（展示用 cost/100.0 + "元"）。

字段命名映射

• 服务端下划线 ➜ SDK 驼峰： trace_id→traceId、address_all→addressAll、geo_list→geoList、walking_distance→walkingDistance。

可缺省字段

• results、results[].routes、distance（关键词/输入提示没有）、geo_list、公交 segments/walking/metrobus/steps/via_stops 等可能为空，渲染前请判空。

---

1 回调类型总览（所有服务统一使用）

所有异步接口均采用：RpcRequestUtils.Callback<T>，包含三类方法：

void onSuccess(T data);
void onBizError(int status, String msg, String traceId);
void onFailure(Exception e);

本指南涉及的 T 有：

• Callback<PlaceTextSearchResponse>（POI：关键词 / 周边 / 输入提示）
• Callback<ReverseGeoResponse>（地理编码：逆）
• Callback<ForwardGeoResponse>（地理编码：正）
• Callback<RouteResponse>（路线规划：步行 / 骑行 / 驾车）
• Callback<BusRouteResponse>（路线规划：公交）

---

2 回调入参 data 是什么？

• data = Callback<T>.onSuccess(T data) 的入参，类型就是泛型 T（见上表）。
• 来源：SDK 将服务端 JSON 反序列化为对应的 POJO。
• 语义：仅当业务成功（status == 10000）才进入 onSuccess 并给出 data；否则走 onBizError(status, msg, traceId)；onFailure(e) 多为网络/超时/解析错误（通常拿不到 traceId）。
• 可空性：data 内部字段（如 results、distance、geo_list 等）可能为 null，请按示例判空。
• 线程：回调不保证主线程；更新 UI 请 runOnUiThread(...)。

快速对照：data 里常用字段

回调	data.traceId	结果主体	常用字段提示
Callback<PlaceTextSearchResponse>	✓	results: List<PlaceItem>	location.lng/lat；周边搜索才常见 distance
Callback<ReverseGeoResponse>	✓	results: List<Result>	addressAll（优先）/address；location.lng/lat
Callback<ForwardGeoResponse>	✓	results.geocodes: List<GeoItem>	location.lng/lat；province/city/district/adcode
Callback<RouteResponse>	✓	results[].routes: List<Route>	routes[].dist(米)、routes[].duration(秒)、routes[].geoList[].latitude/longitude
Callback<BusRouteResponse>	✓	results: List<BusRouteResult>	cost(分)、walkingDistance、segments[].metrobus[]

---

3 响应结构表格约定（本指南统一使用）

• 路径表示：obj.a.b 表示嵌套；数组用 []，如 results[0].location.lng
• 类型：string / int / double / object / array<object>
• 可空：该字段在成功响应中也可能缺省或为 null
• 单位：仅对数值字段标注
• 服务端字段：若与 SDK 字段不同，这里列出服务端原名

---