物流项目第十期（轨迹微服务）

本项目专栏：

物流项目_Auc23的博客-CSDN博客

建议先看这期：

MongoDB入门之Java的使用-CSDN博客

物流项目第九期（MongoDB的应用之作业范围）-CSDN博客

业务需求

快递员取件成功后，需要将订单转成运单，用户会比较关注目前包裹走到哪里，类似这样：

需求描述

轨迹微服务是一个独立的微服务，主要提供创建运单轨迹点、记录最新位置、查询轨迹这些服务，具体要求如下：

• 运单创建成功后，为运单创建轨迹点数据，并且将此数据持久化，以供后续的查询
• 司机端在运输途中，需要上报最新的位置，更新相应的运单的最新位置数据
• 快递员端在运输途中，需要上报最新的位置，更新相应的运单的最新位置数据
• 提供查询轨迹的接口服务
• 为查询轨迹接口服务设置缓存
• 用户签收后，需要关闭轨迹的更新，不再更新最新位置数据

业务流程

MQListener

@Slf4j
@Component
public class MQListener {@Resourceprivate TrackService trackService;/*** 创建运单后创建轨迹** @param msg 消息*/@RabbitListener(bindings = @QueueBinding(value = @Queue(name = Constants.MQ.Queues.TRACK_TRANSPORT_ORDER_CREATED),exchange = @Exchange(name = Constants.MQ.Exchanges.TRANSPORT_ORDER_DELAYED, type = ExchangeTypes.TOPIC, delayed = Constants.MQ.DELAYED),key = Constants.MQ.RoutingKeys.TRANSPORT_ORDER_CREATE))public void listenTransportOrderCreatedMsg(String msg) {log.info("接收到新增运单的消息 ({})-> {}", Constants.MQ.Queues.TRACK_TRANSPORT_ORDER_CREATED, msg);TransportOrderMsg transportOrderMsg = JSONUtil.toBean(msg, TransportOrderMsg.class);this.trackService.create(transportOrderMsg.getId());}/*** 运单签收后完成轨迹** @param msg 消息*/@RabbitListener(bindings = @QueueBinding(value = @Queue(name = Constants.MQ.Queues.TRACK_TRANSPORT_ORDER_UPDATE_STATUS),exchange = @Exchange(name = Constants.MQ.Exchanges.TRANSPORT_ORDER_DELAYED, type = ExchangeTypes.TOPIC, delayed = Constants.MQ.DELAYED),key = Constants.MQ.RoutingKeys.TRANSPORT_ORDER_UPDATE_STATUS_PREFIX + "RECEIVED"))public void listenTransportOrderUpdateStatusMsg(String msg) {log.info("接收到更新运单状态的消息 ({})-> {}", Constants.MQ.Queues.TRACK_TRANSPORT_ORDER_UPDATE_STATUS, msg);TransportOrderStatusMsg transportOrderStatusMsg = JSONUtil.toBean(msg, TransportOrderStatusMsg.class);this.trackService.complete(transportOrderStatusMsg.getIdList());}
}

util

public class TrackEntityUtil {/*** 将 TrackEntity 转换为 TrackDTO* 主要用于接口返回或业务层使用，脱敏敏感字段并格式化数据结构** @param trackEntity 原始实体对象（来自数据库）* @return 转换后的 DTO 对象（用于返回给前端或其他服务）*/public static TrackDTO toDTO(TrackEntity trackEntity) {// 创建 CopyOptions 配置项，指定忽略某些字段的复制// 这里忽略了 planGeoJsonLine 和 lastPoint 字段，因为这两个字段是 GeoJSON 类型，不适合直接暴露给外部// ignoreNullValue 表示不复制 null 值属性，避免空值污染 DTOCopyOptions copyOptions = CopyOptions.create().setIgnoreProperties("planGeoJsonLine", "lastPoint").ignoreNullValue();// 使用 Hutool 的 BeanUtil.toBean 方法进行基础字段拷贝// 会自动将 trackEntity 中非忽略字段复制到 TrackDTO 中TrackDTO trackDTO = BeanUtil.toBean(trackEntity, TrackDTO.class, copyOptions);// 处理计划轨迹点（planGeoJsonLine）：这是一个 GeoJsonLineString 类型的地理轨迹线GeoJsonLineString planGeoJsonLine = trackEntity.getPlanGeoJsonLine();if (ObjectUtil.isAllNotEmpty(planGeoJsonLine, planGeoJsonLine.getCoordinates())) {// 如果轨迹线及其坐标列表存在且非空，则进行转换// 将 GeoJsonLineString 中的坐标点列表转换为 MarkerPointDTO 列表List<MarkerPointDTO> coordinateList = planGeoJsonLine.getCoordinates().stream()// 每个 Coordinate 点转成 MarkerPointDTO（只包含 x 和 y 坐标）.map(point -> new MarkerPointDTO(point.getX(), point.getY()))// 收集为 List<MarkerPointDTO>.collect(Collectors.toList());// 设置到 DTO 的 pointList 字段中，供前端展示使用trackDTO.setPointList(coordinateList);}// 处理最新位置坐标（lastPoint）：是一个 GeoJsonPoint 类型的点if (ObjectUtil.isNotEmpty(trackEntity.getLastPoint())) {// 如果 lastPoint 存在// 获取该点的经纬度信息GeoJsonPoint point = trackEntity.getLastPoint();// 转换成 MarkerPointDTO 并设置到 DTO 中trackDTO.setLastPoint(new MarkerPointDTO(point.getX(), point.getY()));}// 返回最终处理好的 DTO 对象return trackDTO;}}

entity

/*** 轨迹数据** @author zzj* @version 1.0*/
@Data
@Document("sl_track")
public class TrackEntity {@Id@JsonIgnoreprivate ObjectId id;/*** 运单id*/@Indexedprivate String transportOrderId;/*** 规划的轨迹坐标点线（通过地图服务商规划出来的轨迹点）*/private GeoJsonLineString planGeoJsonLine;/*** 距离，单位：米*/private Double distance;/*** 最新的位置坐标，x：经度，y：纬度*/private GeoJsonPoint lastPoint;/*** 状态*/private TrackStatusEnum status;/*** 类型*/private TrackTypeEnum type;/*** 创建时间*/private Long created;/*** 更新时间*/private Long updated;}

enums

/*** 异常枚举** @author zzj* @version 1.0*/
public enum TrackExceptionEnum implements BaseExceptionEnum {TRACK_ALREADY_EXISTS(1001, "轨迹已经存在");private Integer code;private Integer status;private String value;TrackExceptionEnum(Integer code, String value) {this.code = code;this.value = value;this.status = 500;}TrackExceptionEnum(Integer code, Integer status, String value) {this.code = code;this.value = value;this.status = status;}@Overridepublic Integer getCode() {return this.code;}@Overridepublic String getValue() {return this.value;}@Overridepublic Integer getStatus() {return this.status;}public static TrackExceptionEnum codeOf(Integer code) {return EnumUtil.getBy(TrackExceptionEnum::getCode, code);}
}

controller

@RestController
@Api(tags = "轨迹管理")
@RequestMapping("track")
public class TrackController {@Resourceprivate TrackService trackService;@PostMapping@ApiOperation(value = "创建轨迹", notes = "创建轨迹，会完成路线规划")@ApiImplicitParams({@ApiImplicitParam(name = "transportOrderId", value = "运单号", required = true)})public boolean create(@RequestParam("transportOrderId") String transportOrderId) {return this.trackService.create(transportOrderId);}@PutMapping("complete")@ApiOperation(value = "完成轨迹", notes = " 完成轨迹，修改为完成状态")@ApiImplicitParams({@ApiImplicitParam(name = "transportOrderIds", value = "运单号列表", required = true)})public boolean complete(@RequestParam("transportOrderIds") List<String> transportOrderIds) {return this.trackService.complete(transportOrderIds);}/*** 通过运单号查询轨迹** @param transportOrderId 运单号* @return 轨迹数据*/@GetMapping("{transportOrderId}")@ApiOperation(value = "查询轨迹", notes = "通过运单号查询轨迹")@ApiImplicitParams({@ApiImplicitParam(name = "transportOrderId", value = "运单号", required = true)})public TrackDTO queryByTransportOrderId(@PathVariable("transportOrderId") String transportOrderId) {TrackEntity trackEntity = this.trackService.queryByTransportOrderId(transportOrderId);return TrackEntityUtil.toDTO(trackEntity);}@PutMapping("upload/truck")@ApiOperation(value = "车辆上报位置", notes = "车辆上报位置")@ApiImplicitParams({@ApiImplicitParam(name = "transportTaskId", value = "运输任务id", required = true),@ApiImplicitParam(name = "lng", value = "经度", required = true),@ApiImplicitParam(name = "lat", value = "纬度", required = true),})public boolean uploadFromTruck(@RequestParam("transportTaskId") Long transportTaskId,@RequestParam("lng") double lng,@RequestParam("lat") double lat) {return this.trackService.uploadFromTruck(transportTaskId, lng, lat);}@PutMapping("upload/courier")@ApiOperation(value = "快递员上报位置", notes = "快递员上报位置")@ApiImplicitParams({@ApiImplicitParam(name = "transportOrderIds", value = "运单号列表", required = true),@ApiImplicitParam(name = "lng", value = "经度", required = true),@ApiImplicitParam(name = "lat", value = "纬度", required = true),})public boolean uploadFromCourier(@RequestParam("transportOrderIds") List<String> transportOrderIds,@RequestParam("lng") double lng,@RequestParam("lat") double lat) {return this.trackService.uploadFromCourier(transportOrderIds, lng, lat);}}

service

/*** 轨迹服务** @author zzj* @version 1.0*/
public interface TrackService {/*** 创建轨迹，会完成路线规划** @param transportOrderId 运单号* @return 是否成功*/boolean create(String transportOrderId);/*** 完成轨迹，修改为完成状态** @param transportOrderIds 运单号列表* @return 是否成功*/boolean complete(List<String> transportOrderIds);/*** 通过运单号查询轨迹** @param transportOrderId 运单号* @return 轨迹数据*/TrackEntity queryByTransportOrderId(String transportOrderId);/*** 车辆上报位置** @param transportTaskId 运输任务id* @param lng             经度* @param lat             纬度* @return 是否成功*/boolean uploadFromTruck(Long transportTaskId, double lng, double lat);/*** 快递员上报位置** @param transportOrderIds 运单号列表* @param lng               经度* @param lat               纬度* @return 是否成功*/boolean uploadFromCourier(List<String> transportOrderIds, double lng, double lat);}

实现接口

/*** TrackServiceImpl 是一个服务实现类，用于处理物流轨迹相关的业务逻辑。* 包括创建轨迹、更新状态、路径规划、位置上报等功能。*/
@Service // Spring 注解，表示这是一个服务层 Bean，可被自动注入使用
public class TrackServiceImpl implements TrackService {/*** MongoDB 操作模板，用于持久化 TrackEntity 数据*/@Resourceprivate MongoTemplate mongoTemplate;/*** 自定义的地图服务模板（如封装了高德地图 API），用于路径规划等地理操作*/@Resourceprivate EagleMapTemplate eagleMapTemplate;/*** Feign 客户端，用于调用运输订单微服务接口*/@Resourceprivate TransportOrderFeign transportOrderFeign;/*** Feign 客户端，用于调用运输任务微服务接口*/@Resourceprivate TransportTaskFeign transportTaskFeign;/*** Feign 客户端，用于调用订单微服务接口*/@Resourceprivate OrderFeign orderFeign;/*** Feign 客户端，用于调用组织机构微服务接口*/@Resourceprivate OrganFeign organFeign;/*** 创建一个新的物流轨迹记录** @param transportOrderId 运单 ID* @return 是否创建成功*/@Overridepublic boolean create(String transportOrderId) {// 构造查询条件：根据 transportOrderId 查询是否已有对应轨迹记录Query query = Query.query(Criteria.where("transportOrderId").is(transportOrderId));// 从 MongoDB 中查找是否存在该运单的轨迹信息TrackEntity trackEntity = mongoTemplate.findOne(query, TrackEntity.class);// 如果已经存在轨迹数据，则抛出自定义异常 TRACK_ALREADY_EXISTSif (ObjectUtil.isNotEmpty(trackEntity)) {throw new SLException(TrackExceptionEnum.TRACK_ALREADY_EXISTS);}// 创建新的轨迹实体对象TrackEntity track = new TrackEntity();track.setTransportOrderId(transportOrderId); // 设置运单 IDtrack.setStatus(TrackStatusEnum.NEW); // 设置初始状态为“新建”track.setCreated(System.currentTimeMillis()); // 设置创建时间戳track.setUpdated(track.getCreated()); // 初始更新时间等于创建时间// 调用方法获取计划路线 GeoJSON 线段，并设置到轨迹实体中track.setPlanGeoJsonLine(this.queryPlanGeoJsonLineString(transportOrderId, track));// 将新创建的轨迹实体保存到 MongoDBthis.mongoTemplate.save(track);// 返回 true 表示创建成功return true;}/*** 获取计划路线的 GeoJsonLineString（即路径线）** @param transportOrderId 运单 ID* @param track            当前轨迹实体（用于设置距离等属性）* @return GeoJsonLineString 表示路径线*/private GeoJsonLineString queryPlanGeoJsonLineString(String transportOrderId, TrackEntity track) {// 通过 Feign 接口获取运输订单详情TransportOrderDTO transportOrderDTO = transportOrderFeign.findById(transportOrderId);// 获取运输线路字符串（通常是 JSON 格式的运输节点列表）String transportLine = transportOrderDTO.getTransportLine();String wayPoints = null;// 如果运输线路不为空if (StrUtil.isNotEmpty(transportLine)) {// 解析成 JSON 对象JSONObject transportLineJson = JSONUtil.parseObj(transportLine);// 获取节点列表 JSONArrayJSONArray nodeList = transportLineJson.getJSONArray("nodeList");// 遍历每个节点，提取经纬度并格式化为 "lng,lat" 字符串List<String> pointList = nodeList.stream().map(obj -> {JSONObject json = (JSONObject) obj;double longitude = json.getDouble("longitude", 0d);double latitude = json.getDouble("latitude", 0d);// 如果经纬度为 0，标记为错误点if (ObjectUtil.equalsAny(0d, longitude, latitude)) {return "err";}// 正常点则格式化为字符串return StrUtil.format("{},{}", longitude, latitude);})// 过滤掉错误点.filter(o -> ObjectUtil.notEqual(o, "err")).collect(Collectors.toList());// 多个坐标点之间用分号拼接，作为途经点参数wayPoints = StrUtil.join(";", pointList);} else {// 如果没有运输线路信息，则尝试获取当前网点的经纬度作为起点OrganDTO organDTO = this.organFeign.queryById(transportOrderDTO.getCurrentAgencyId());if (ObjectUtil.isNotEmpty(organDTO)) {// 使用网点坐标作为途经点wayPoints = StrUtil.format("{},{}", organDTO.getLongitude(), organDTO.getLatitude());} else {// 理论上不会出现这种情况，如果没有就不设置途经点}}// 获取订单的位置信息（发货地和收货地）OrderLocationDTO orderLocationDTO = this.orderFeign.findOrderLocationByOrderId(transportOrderDTO.getOrderId());// 格式化发货地和收货地坐标CoordinateUtil.Coordinate origin = CoordinateUtil.format(orderLocationDTO.getSendLocation());CoordinateUtil.Coordinate destination = CoordinateUtil.format(orderLocationDTO.getReceiveLocation());// 构建请求参数 MapMap<String, Object> param = MapUtil.<String, Object>builder().put(ObjectUtil.isNotEmpty(wayPoints), "waypoints", wayPoints) // 添加途经点（如果有的话）.put("show_fields", "polyline") // 请求返回 polyline 字段.build();// 调用地图服务，获取驾车路线规划结果String driving = this.eagleMapTemplate.opsForDirection().driving(ProviderEnum.AMAP, new Coordinate(origin), new Coordinate(destination), param);// 如果返回为空，说明调用失败或无结果if (StrUtil.isEmpty(driving)) {return null;}// 解析返回的 JSON 数据JSONObject jsonObject = JSONUtil.parseObj(driving);// 提取总距离Double distance = Convert.toDouble(jsonObject.getByPath("route.paths[0].distance"), -1d);track.setDistance(distance); // 设置到轨迹实体中// 提取步骤列表JSONArray steps = jsonObject.getByPath("route.paths[0].steps", JSONArray.class);// 收集所有坐标点List<Point> points = new ArrayList<>();// 获取所有 polyline 字段值（每一步的坐标点集合）List<Object> polyLines = CollUtil.getFieldValues(steps, "polyline");for (Object polyLine : polyLines) {// 将 polyline 字符串拆分成多个坐标点List<GeoJsonPoint> list = StrUtil.split(Convert.toStr(polyLine), ';').stream().map(coordinateStr -> {// 拆分为 lng 和 latdouble[] ds = Convert.convert(double[].class, StrUtil.splitTrim(coordinateStr, ','));return new GeoJsonPoint(ds[0], ds[1]);}).collect(Collectors.toList());// 添加到总坐标点列表中points.addAll(list);}// 返回构造好的 GeoJsonLineString（代表整条路径线）return new GeoJsonLineString(points);}/*** 批量完成轨迹记录（更新状态为 COMPLETE）** @param transportOrderIds 运单 ID 列表* @return 是否有记录被修改*/@Overridepublic boolean complete(List<String> transportOrderIds) {// 构造查询条件：匹配 transportOrderId 在传入列表中的记录，且状态为 NEWQuery query = Query.query(Criteria.where("transportOrderId").in(transportOrderIds));// 构造更新语句：将 status 更新为 COMPLETEUpdate update = Update.update("status", TrackStatusEnum.COMPLETE);// 执行批量更新UpdateResult updateResult = this.mongoTemplate.updateMulti(query, update, TrackEntity.class);// 如果修改了至少一条记录，返回 truereturn updateResult.getModifiedCount() > 0;}/*** 根据运单 ID 查询轨迹实体** @param transportOrderId 运单 ID* @return 查询到的 TrackEntity 实体对象 或 null*/@Overridepublic TrackEntity queryByTransportOrderId(String transportOrderId) {// 构造查询条件：按 transportOrderId 查询Query query = Query.query(Criteria.where("transportOrderId").is(transportOrderId));// 查询唯一匹配的记录return this.mongoTemplate.findOne(query, TrackEntity.class);}/*** 司机端上报当前位置** @param transportTaskId 运输任务 ID* @param lng             经度* @param lat             纬度* @return 是否上报成功*/@Overridepublic boolean uploadFromTruck(Long transportTaskId, double lng, double lat) {// 根据运输任务 ID 查询对应的运单 ID 列表List<String> list = this.transportTaskFeign.queryTransportOrderIdListById(transportTaskId);// 调用通用上传方法，类型为 DRIVERreturn upload(list, lng, lat, TrackTypeEnum.DRIVER);}/*** 快递员端上报当前位置** @param transportOrderIds 运单 ID 列表* @param lng               经度* @param lat               纬度* @return 是否上报成功*/@Overridepublic boolean uploadFromCourier(List<String> transportOrderIds, double lng, double lat) {// 直接调用通用上传方法，类型为 COURIERreturn upload(transportOrderIds, lng, lat, TrackTypeEnum.COURIER);}/*** 通用位置上报逻辑** @param transportOrderIds 运单 ID 列表* @param lng               经度* @param lat               纬度* @param trackTypeEnum     上报类型（DRIVER/COURIER）* @return 是否更新成功*/private boolean upload(List<String> transportOrderIds, double lng, double lat, TrackTypeEnum trackTypeEnum) {// 如果运单列表为空，直接返回 falseif (CollUtil.isEmpty(transportOrderIds)) {return false;}// 构造查询条件：transportOrderId 在列表中，且状态为 NEWQuery query = Query.query(Criteria.where("transportOrderId").in(transportOrderIds).and("status").is(TrackStatusEnum.NEW));// 构造更新内容：更新 lastPoint（最新位置）、type（轨迹类型）、updated（更新时间）Update update = Update.update("lastPoint", new GeoJsonPoint(lng, lat)).set("type", trackTypeEnum).set("updated", System.currentTimeMillis());// 执行批量更新UpdateResult updateResult = this.mongoTemplate.updateMulti(query, update, TrackEntity.class);// 返回是否成功更新（是否有记录被修改）return updateResult.getModifiedCount() > 0;}
}