簡(jiǎn)介這是一份面向Java后端開發(fā)者與小程序入門者的實(shí)戰(zhàn)型項(xiàng)目源碼圍繞小程序地圖定位場(chǎng)景演示如何用Java服務(wù)端配合前端完成位置服務(wù)。內(nèi)容涉及GPS與網(wǎng)絡(luò)定位、地理編碼與反地理編碼、路徑規(guī)劃、定位數(shù)據(jù)實(shí)時(shí)更新、隱私安全處理及前后端接口設(shè)計(jì)等關(guān)鍵環(huán)節(jié)適合想打通地圖定位鏈路的初中級(jí)開發(fā)者參考。資源包共38個(gè)文件約314KB以15個(gè)png界面截圖與圖標(biāo)、6個(gè)js邏輯腳本、5個(gè)wxss樣式、4個(gè)wxml頁面結(jié)構(gòu)及4個(gè)json配置為主另含說明文檔與開源協(xié)議目錄按pages、utils、image等模塊劃分結(jié)構(gòu)清晰便于按需查閱。目前已有155人學(xué)習(xí)下載。通過閱讀源碼讀者可理解地圖定位小程序的整體組織方式掌握定位接口調(diào)用、頁面交互與樣式布局的落地寫法并借鑒其錯(cuò)誤處理與性能優(yōu)化思路快速搭建自己的定位類小程序原型。1. 基于 Java 開發(fā)的小程序地圖定位從后端坐標(biāo)到前端標(biāo)記的完整鏈路用戶打開小程序地圖上立刻出現(xiàn)自己的位置和一個(gè)附近的門店標(biāo)記點(diǎn)一下還能看到距離和導(dǎo)航按鈕。這個(gè)體驗(yàn)背后其實(shí)是一條跨端鏈路微信小程序端負(fù)責(zé)采集經(jīng)緯度、渲染地圖組件Java 后端負(fù)責(zé)坐標(biāo)轉(zhuǎn)換、距離計(jì)算和業(yè)務(wù)數(shù)據(jù)組裝。很多團(tuán)隊(duì)第一次做的時(shí)候前端能顯示藍(lán)點(diǎn)后端卻拿不到可用坐標(biāo)或者標(biāo)記偏移幾百米問題往往出在坐標(biāo)系沒對(duì)齊、權(quán)限沒配全、接口沒做逆地理編碼。這篇筆記就圍繞「基于 Java 開發(fā)的小程序地圖定位」這個(gè)方向把小程序端wx.getLocation、map組件、Java 側(cè)坐標(biāo)糾偏、距離排序、緩存策略和常見翻車點(diǎn)一次講透。適合正在做門店導(dǎo)航、打卡簽到、配送范圍判斷、附近的人這類功能的開發(fā)者新手能照著跑通最小閉環(huán)熟手能直接拿去對(duì)照參數(shù)和邊界。2. 小程序端定位能力拆解getLocation、map 組件與權(quán)限配置2.1 三種定位精度怎么選wgs84、gcj02、bd09 的實(shí)際差異微信小程序wx.getLocation的type參數(shù)只有兩個(gè)合法值wgs84和gcj02。wgs84是 GPS 原始坐標(biāo)系gcj02是國測(cè)局加密后的坐標(biāo)系也就是常說的火星坐標(biāo)。如果你直接把wgs84的經(jīng)緯度丟到微信map組件上標(biāo)記會(huì)偏移幾百米因?yàn)槲⑿诺貓D底層用的是gcj02。百度地圖的bd09又是在gcj02基礎(chǔ)上二次偏移小程序原生地圖組件不認(rèn)這個(gè)坐標(biāo)系必須轉(zhuǎn)成gcj02才能正常顯示。我一般會(huì)這樣選只要是在微信生態(tài)內(nèi)展示統(tǒng)一用gcj02如果后端還要對(duì)接第三方 GPS 設(shè)備或高精度軌跡才在入庫時(shí)保留wgs84展示前再轉(zhuǎn)。轉(zhuǎn)換算法網(wǎng)上有現(xiàn)成的transform函數(shù)但要注意它只適用于中國大陸范圍境外坐標(biāo)不要做偏移否則會(huì)引入新的誤差。// 小程序端獲取 gcj02 坐標(biāo)直接可用于 map 組件 wx.getLocation({ type: gcj02, isHighAccuracy: true, // 開啟高精度定位iOS 上會(huì)額外請(qǐng)求一次 highAccuracyExpireTime: 4000, // 高精度定位超時(shí)時(shí)間單位毫秒 success(res) { const { latitude, longitude, accuracy } res // accuracy 是水平精度單位米大于 100 時(shí)建議提示用戶到空曠處 console.log(定位結(jié)果, latitude, longitude, accuracy) }, fail(err) { // errMsg 常見值getLocation:fail auth deny / system permission denied console.error(定位失敗, err) } })這段代碼里isHighAccuracy和highAccuracyExpireTime是容易被忽略的參數(shù)。不開高精度時(shí)安卓部分機(jī)型返回的是基站或 Wi-Fi 定位誤差可能到 500 米以上開了之后系統(tǒng)會(huì)嘗試 GPS但耗時(shí)更長(zhǎng)所以超時(shí)時(shí)間要設(shè)一個(gè)合理值我通常給 3000 到 5000 毫秒。accuracy字段一定要讀它是判斷這次定位能不能用的關(guān)鍵超過 100 米就別直接拿來算配送范圍了。2.2 app.json 里必須聲明的權(quán)限與隱私協(xié)議從 2022 年開始微信對(duì)地理位置接口收緊了權(quán)限校驗(yàn)。如果app.json里沒有聲明requiredPrivateInfoswx.getLocation會(huì)直接失敗報(bào)getLocation:fail the api need to be declared in the requiredPrivateInfos field in app.json。這個(gè)坑我見過太多次尤其是老項(xiàng)目升級(jí)基礎(chǔ)庫之后突然定位不可用。{ requiredPrivateInfos: [ getLocation, chooseLocation, choosePoi ], permission: { scope.userLocation: { desc: 你的位置信息將用于展示附近門店和計(jì)算距離 } } }requiredPrivateInfos里按實(shí)際用到的接口填不要多寫否則審核時(shí)會(huì)被問用途。permission里的desc會(huì)出現(xiàn)在系統(tǒng)授權(quán)彈窗上寫清楚業(yè)務(wù)用途通過率更高。另外如果小程序涉及隱私協(xié)議還要在app.json里配置__usePrivacyCheck__并在用戶首次觸發(fā)定位前調(diào)用wx.requirePrivacyAuthorize否則新版本基礎(chǔ)庫會(huì)攔截。2.3 map 組件標(biāo)記渲染markers、polyline 與 callout 的參數(shù)邊界拿到坐標(biāo)之后map組件的markers數(shù)組是展示核心。每個(gè) marker 的id必須是數(shù)字latitude和longitude必填iconPath支持本地路徑和網(wǎng)絡(luò)路徑但網(wǎng)絡(luò)圖片需要先下載到本地臨時(shí)文件否則部分安卓機(jī)型不顯示。callout用來做氣泡display: ALWAYS會(huì)常駐顯示適合展示門店名和距離。Page({ data: { latitude: 39.908, longitude: 116.397, markers: [] }, onLoad() { this.loadNearbyStores() }, loadNearbyStores() { wx.request({ url: https://your-java-api.com/api/stores/nearby, data: { lat: this.data.latitude, lng: this.data.longitude, radius: 3000 }, success: (res) { const markers res.data.list.map((item, index) ({ id: index 1, latitude: item.lat, longitude: item.lng, width: 32, height: 32, iconPath: /assets/store-pin.png, callout: { content: ${item.name} ${item.distance}m, display: ALWAYS, padding: 6, borderRadius: 4, fontSize: 12 } })) this.setData({ markers }) } }) } })這里有個(gè)性能邊界markers超過 200 個(gè)之后低端安卓機(jī)渲染會(huì)明顯卡頓。常見做法是按縮放級(jí)別做聚合或者只返回視野范圍內(nèi)的點(diǎn)。polyline用來畫路線點(diǎn)數(shù)量超過 1000 時(shí)建議后端抽稀否則小程序端會(huì)掉幀。3. Java 后端坐標(biāo)處理糾偏、距離計(jì)算與逆地理編碼3.1 wgs84 轉(zhuǎn) gcj02 的 Java 實(shí)現(xiàn)與邊界判斷后端拿到的坐標(biāo)可能來自小程序gcj02也可能來自硬件wgs84。如果數(shù)據(jù)庫里混存兩種坐標(biāo)系距離計(jì)算就會(huì)出錯(cuò)。我一般會(huì)在入庫時(shí)統(tǒng)一轉(zhuǎn)成gcj02轉(zhuǎn)換函數(shù)用經(jīng)典的transformLat和transformLng公式注意outOfChina判斷境外坐標(biāo)直接返回原值。public class CoordTransform { private static final double PI 3.1415926535897932384626; private static final double A 6378245.0; private static final double EE 0.00669342162296594323; public static boolean outOfChina(double lat, double lng) { return lng 72.004 || lng 137.8347 || lat 0.8293 || lat 55.8271; } public static double[] wgs84ToGcj02(double lat, double lng) { if (outOfChina(lat, lng)) { return new double[]{lat, lng}; } double dLat transformLat(lng - 105.0, lat - 35.0); double dLng transformLng(lng - 105.0, lat - 35.0); double radLat lat / 180.0 * PI; double magic Math.sin(radLat); magic 1 - EE * magic * magic; double sqrtMagic Math.sqrt(magic); dLat (dLat * 180.0) / ((A * (1 - EE)) / (magic * sqrtMagic) * PI); dLng (dLng * 180.0) / (A / sqrtMagic * Math.cos(radLat) * PI); return new double[]{lat dLat, lng dLng}; } private static double transformLat(double x, double y) { double ret -100.0 2.0 * x 3.0 * y 0.2 * y * y 0.1 * x * y 0.2 * Math.sqrt(Math.abs(x)); ret (20.0 * Math.sin(6.0 * x * PI) 20.0 * Math.sin(2.0 * x * PI)) * 2.0 / 3.0; ret (20.0 * Math.sin(y * PI) 40.0 * Math.sin(y / 3.0 * PI)) * 2.0 / 3.0; ret (160.0 * Math.sin(y / 12.0 * PI) 320 * Math.sin(y * PI / 30.0)) * 2.0 / 3.0; return ret; } private static double transformLng(double x, double y) { double ret 300.0 x 2.0 * y 0.1 * x * x 0.1 * x * y 0.1 * Math.sqrt(Math.abs(x)); ret (20.0 * Math.sin(6.0 * x * PI) 20.0 * Math.sin(2.0 * x * PI)) * 2.0 / 3.0; ret (20.0 * Math.sin(x * PI) 40.0 * Math.sin(x / 3.0 * PI)) * 2.0 / 3.0; ret (150.0 * Math.sin(x / 12.0 * PI) 300.0 * Math.sin(x / 30.0 * PI)) * 2.0 / 3.0; return ret; } }這段代碼的outOfChina判斷很關(guān)鍵少了它境外坐標(biāo)會(huì)被錯(cuò)誤偏移。A是克拉索夫斯基橢球長(zhǎng)半軸EE是第一偏心率平方這兩個(gè)常數(shù)不要改。轉(zhuǎn)換精度在米級(jí)足夠門店導(dǎo)航用但如果做測(cè)繪級(jí)應(yīng)用需要更復(fù)雜的七參數(shù)轉(zhuǎn)換。3.2 Haversine 距離計(jì)算與 SQL 層排序優(yōu)化算距離最常用的是 Haversine 公式Java 里直接實(shí)現(xiàn)就行。但如果在數(shù)據(jù)庫里對(duì)全表逐行算距離數(shù)據(jù)量上萬之后會(huì)非常慢。我一般會(huì)先用一個(gè)矩形范圍過濾再用 Haversine 精算。public class GeoUtils { private static final double EARTH_RADIUS 6371000; // 地球平均半徑單位米 public static double haversine(double lat1, double lng1, double lat2, double lng2) { double dLat Math.toRadians(lat2 - lat1); double dLng Math.toRadians(lng2 - lng1); double a Math.sin(dLat / 2) * Math.sin(dLat / 2) Math.cos(Math.toRadians(lat1)) * Math.cos(Math.toRadians(lat2)) * Math.sin(dLng / 2) * Math.sin(dLng / 2); double c 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a)); return EARTH_RADIUS * c; } }對(duì)應(yīng)的 SQL 先用經(jīng)緯度范圍縮小候選集lat和lng字段建聯(lián)合索引SELECT id, name, lat, lng, (6371000 * ACOS( COS(RADIANS(#{lat})) * COS(RADIANS(lat)) * COS(RADIANS(lng) - RADIANS(#{lng})) SIN(RADIANS(#{lat})) * SIN(RADIANS(lat)) )) AS distance FROM store WHERE lat BETWEEN #{minLat} AND #{maxLat} AND lng BETWEEN #{minLng} AND #{maxLng} HAVING distance #{radius} ORDER BY distance ASC LIMIT 50;minLat、maxLat這些邊界值由后端根據(jù)半徑和緯度算出緯度越高經(jīng)度跨度越大公式是lngRange radius / (111320 * cos(lat))。這樣能把掃描行數(shù)從全表降到幾千行以內(nèi)。注意HAVING在 MySQL 里可以用別名但部分?jǐn)?shù)據(jù)庫不支持換成子查詢更穩(wěn)。3.3 逆地理編碼把經(jīng)緯度變成「XX路XX號(hào)」用戶看到的不能只是經(jīng)緯度需要地址。逆地理編碼一般走第三方服務(wù)Java 側(cè)封裝一個(gè)帶緩存的方法避免每次定位都請(qǐng)求外部接口。Service public class GeocoderService { Cacheable(value geocode, key #lat , #lng) public String reverse(double lat, double lng) { // 調(diào)用地圖開放平臺(tái)逆地理編碼接口 // 注意不同平臺(tái)坐標(biāo)系要求不同傳入前確認(rèn)是否需要 gcj02 String url String.format(https://restapi.amap.com/v3/geocode/regeo?location%f,%fkey%s, lng, lat, apiKey); // 解析 JSON取 regeocode.formatted_address return parseAddress(url); } }緩存 key 用經(jīng)緯度拼接精度保留 6 位小數(shù)大約 0.1 米足夠復(fù)用。緩存時(shí)間我一般設(shè) 24 小時(shí)因?yàn)榈刂凡粫?huì)頻繁變。注意高德、騰訊等平臺(tái)的接口對(duì)坐標(biāo)系要求不同傳錯(cuò)會(huì)返回錯(cuò)誤地址這個(gè)坑后面會(huì)細(xì)說。4. 前后端聯(lián)調(diào)與數(shù)據(jù)一致性接口設(shè)計(jì)、緩存與并發(fā)4.1 附近門店接口的請(qǐng)求參數(shù)與返回結(jié)構(gòu)接口設(shè)計(jì)要一次定清楚避免前端反復(fù)改。我常用的請(qǐng)求參數(shù)是lat、lng、radius、page、size返回里帶distance和address。參數(shù)類型必填說明latdouble是gcj02 緯度保留 6 位小數(shù)lngdouble是gcj02 經(jīng)度保留 6 位小數(shù)radiusint否搜索半徑單位米默認(rèn) 3000最大 10000pageint否頁碼從 1 開始sizeint否每頁條數(shù)默認(rèn) 20最大 50返回結(jié)構(gòu)里list每項(xiàng)包含id、name、lat、lng、distance、address。distance由后端算好前端不再重復(fù)計(jì)算避免兩端精度不一致。4.2 Redis GEO 與本地緩存的取舍如果門店數(shù)據(jù)量大、查詢頻繁可以用 Redis 的 GEO 結(jié)構(gòu)。GEOADD入庫GEORADIUS查詢性能比 SQL 好一個(gè)量級(jí)。但 Redis GEO 底層是 geohash精度約 0.6 米對(duì)門店導(dǎo)航足夠。缺點(diǎn)是數(shù)據(jù)同步需要額外維護(hù)門店增刪改時(shí)要同時(shí)更新 Redis 和數(shù)據(jù)庫。// Redis GEO 寫入 redisTemplate.opsForGeo().add(store:geo, new Point(lng, lat), storeId); // 查詢附近 3 公里 Circle circle new Circle(new Point(lng, lat), new Distance(3000, Metrics.METRIC)); GeoResultsRedisGeoCommands.GeoLocationString results redisTemplate.opsForGeo().radius(store:geo, circle);如果門店數(shù)量在幾千以內(nèi)我建議直接用 SQL少一個(gè)中間件少一份一致性負(fù)擔(dān)。超過幾萬再上 Redis GEO并且要做好緩存擊穿和雪崩的兜底。4.3 定位數(shù)據(jù)的一致性坐標(biāo)系、精度與時(shí)間戳一致性有三個(gè)維度坐標(biāo)系一致、精度標(biāo)記一致、時(shí)間戳有效。坐標(biāo)系前面說了統(tǒng)一gcj02。精度標(biāo)記是指每次定位都記錄accuracy后端在算距離時(shí)如果accuracy大于 200 米可以降權(quán)或提示用戶重新定位。時(shí)間戳是指定位結(jié)果超過 30 秒就視為過期尤其是配送場(chǎng)景用戶可能已經(jīng)移動(dòng)了。public class LocationDTO { private double lat; private double lng; private double accuracy; private long timestamp; public boolean isExpired() { return System.currentTimeMillis() - timestamp 30_000; } public boolean isReliable() { return accuracy 0 accuracy 200; } }這兩個(gè)方法在業(yè)務(wù)層調(diào)用過期或不可靠的定位直接返回錯(cuò)誤碼讓前端重新獲取不要拿舊數(shù)據(jù)硬算。5. 地圖定位避坑排查坐標(biāo)偏移、權(quán)限拒絕與真機(jī)差異5.1 標(biāo)記偏移幾百米坐標(biāo)系混用的典型現(xiàn)象現(xiàn)象小程序地圖上藍(lán)點(diǎn)位置正確但門店標(biāo)記整體偏移方向不固定有時(shí)偏東有時(shí)偏北。原因門店數(shù)據(jù)入庫時(shí)用的是wgs84小程序地圖用gcj02兩者差 300 到 500 米。解決入庫前統(tǒng)一轉(zhuǎn)gcj02或者查詢時(shí)在 Java 側(cè)轉(zhuǎn)換。檢查方法是拿一個(gè)已知地標(biāo)的經(jīng)緯度分別用兩種坐標(biāo)系渲染看哪個(gè)和實(shí)際重合。5.2 getLocation 報(bào) auth deny權(quán)限聲明與用戶拒絕的區(qū)分現(xiàn)象調(diào)用wx.getLocation直接失敗errMsg是getLocation:fail auth deny。原因有兩種一是app.json沒配requiredPrivateInfos二是用戶之前拒絕過授權(quán)。解決先檢查配置再調(diào)用wx.getSetting看scope.userLocation是否為 false。如果是用戶拒絕引導(dǎo)用戶去wx.openSetting重新開啟不要反復(fù)彈窗否則會(huì)被微信判定為騷擾。5.3 安卓正常 iOS 偏移高精度定位的機(jī)型差異現(xiàn)象同一地點(diǎn)安卓機(jī)定位準(zhǔn)iPhone 偏幾十米。原因iOS 的isHighAccuracy行為不同部分系統(tǒng)版本下高精度定位會(huì)返回緩存值。解決在success里判斷accuracy大于 50 米時(shí)延遲 1 秒重新調(diào)用一次或者提示用戶「正在校準(zhǔn)」。另外 iOS 的highAccuracyExpireTime不要設(shè)太短建議 5000 毫秒以上。5.4 逆地理編碼返回錯(cuò)誤地址坐標(biāo)系傳反了現(xiàn)象經(jīng)緯度明明在北京逆地理編碼返回的卻是河北某地。原因高德接口要求gcj02如果傳了wgs84偏移后落到了錯(cuò)誤區(qū)域。解決調(diào)用前確認(rèn)坐標(biāo)系必要時(shí)先轉(zhuǎn)gcj02。另外注意經(jīng)緯度順序高德是「經(jīng)度,緯度」百度是「緯度,經(jīng)度」傳反了也會(huì)出錯(cuò)。5.5 真機(jī)調(diào)試正常體驗(yàn)版定位失敗現(xiàn)象開發(fā)者工具里定位正常體驗(yàn)版或正式版報(bào)錯(cuò)。原因體驗(yàn)版和正式版走的是線上域名如果request合法域名沒配接口請(qǐng)求失敗定位數(shù)據(jù)拿不到。解決在小程序后臺(tái)配置request合法域名并且確保 HTTPS 證書有效。另外體驗(yàn)版需要把體驗(yàn)成員加入白名單否則權(quán)限接口可能被限制。6. 進(jìn)階技巧用地理圍欄做打卡簽到與配送范圍判斷地理圍欄是地圖定位里最實(shí)用的進(jìn)階能力。核心思路是給定一個(gè)中心點(diǎn)和半徑判斷用戶當(dāng)前坐標(biāo)是否在范圍內(nèi)。Java 側(cè)用 Haversine 算距離小于半徑即命中。但實(shí)際業(yè)務(wù)里圍欄往往不是圓形而是多邊形比如園區(qū)邊界、配送區(qū)域。這時(shí)候要用射線法判斷點(diǎn)是否在多邊形內(nèi)。public class GeoFence { // 射線法判斷點(diǎn)是否在多邊形內(nèi) public static boolean contains(double lat, double lng, Listdouble[] polygon) { int crossings 0; for (int i 0; i polygon.size(); i) { double[] p1 polygon.get(i); double[] p2 polygon.get((i 1) % polygon.size()); if (((p1[0] lat) ! (p2[0] lat)) (lng (p2[1] - p1[1]) * (lat - p1[0]) / (p2[0] - p1[0]) p1[1])) { crossings; } } return crossings % 2 1; } }polygon是經(jīng)緯度點(diǎn)列表按順時(shí)針或逆時(shí)針排列。射線法對(duì)簡(jiǎn)單多邊形有效自相交多邊形需要先做分割。性能上一個(gè)多邊形幾十個(gè)點(diǎn)單次判斷微秒級(jí)完全夠用。打卡簽到場(chǎng)景還要考慮「漂移」用戶站在圍欄邊緣GPS 抖動(dòng)會(huì)導(dǎo)致一會(huì)兒在內(nèi)一會(huì)兒在外。我的做法是加一個(gè)緩沖帶比如圍欄半徑 100 米實(shí)際判斷用 80 米留 20 米容差。另外記錄打卡時(shí)的accuracy超過 100 米直接拒絕讓用戶重新定位。配送范圍判斷則相反要寬松一點(diǎn)因?yàn)橛脩艨赡芫驮谶吔缟?。我一般用「中心點(diǎn) 半徑」做初篩再用多邊形精判兩層都通過才放行。這樣既快又準(zhǔn)。驗(yàn)證方法很簡(jiǎn)單在開發(fā)者工具里用「模擬位置」功能把坐標(biāo)設(shè)到圍欄內(nèi)外各測(cè)一次看接口返回是否符合預(yù)期。真機(jī)上再拿兩個(gè)手機(jī)一個(gè)在范圍內(nèi)一個(gè)在范圍外對(duì)比結(jié)果。我踩過的最大坑是忘了把圍欄數(shù)據(jù)也轉(zhuǎn)成gcj02結(jié)果整個(gè)園區(qū)偏移用戶明明在門口卻打不了卡。從那以后我在所有坐標(biāo)入庫的地方都加了一行日志打印原始坐標(biāo)和轉(zhuǎn)換后坐標(biāo)方便回溯。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取