简介这是一套面向Java Web与Android初学者及课程设计者的物流管理系统完整源码采用JSP、Servlet、Android与Ajax异步交互技术实现数据库选用开源MySQL服务端按表现层、业务层、数据访问层分层设计表现层基于MVC结构业务层为每个模块提供独立接口与实现类便于应对业务变更并适配不同数据库。压缩包共899个文件约9.48MB其中47个java源文件与47个class文件构成核心业务逻辑32个jsp页面与116个js脚本支撑前后端交互另有大量gif、png、jpg图片资源及css样式、jar依赖包整体结构完整。目前已有506人学习下载。读者可从中获得一套可直接运行的物流管理项目参考理解Servlet与Ajax协同、分层架构与数据库访问的落地方式适合作为毕业设计、课程作业或Java Web入门练手素材。1. 物流管理系统从零落地Android 端加 Java 服务端到底怎么搭很多做毕设或接私活的兄弟拿到「基于 Android 的物流管理系统服务端 Java 实现」这个题目时第一反应是去搜一套现成源码跑起来交差。但真到答辩或上线面试官或甲方一句「你这个运单状态流转怎么保证不丢单」就能把人问住。这个标题背后其实是一套典型的 C/S 架构Android 客户端负责快递员揽收、司机运输、客户查件这些移动场景Java 服务端负责订单、运单、车辆、用户权限和状态机。它适合两类人——想用真实业务练手 Android Spring Boot 全栈的学生以及需要快速搭一套内部物流调度工具的小团队。核心难点不在界面而在服务端接口设计、运单状态一致性和两端数据同步。下面按我实际搭过的一套方案把选型、建表、接口、联调和踩坑讲透。2. 服务端技术选型与数据库表结构设计2.1 为什么选 Spring Boot MyBatis 而不是纯 Servlet标题写的是「服务端 Java 实现」范围很宽。常见做法是用 Spring Boot 起一个单体服务配 MyBatis 做持久层MySQL 存业务数据。理由很直接物流系统里运单、车辆、网点、用户之间有大量关联查询MyBatis 手写 SQL 对复杂条件筛选和分页更可控Spring Boot 内嵌 Tomcat打包成 jar 直接java -jar就能跑部署到一台 2 核 4G 的云主机上足够支撑小规模使用。如果团队后续要拆微服务Spring Boot 的模块划分也容易迁移。不推荐一上来就上 Spring Cloud物流管理系统的并发量通常没到那个级别注册中心、网关、链路追踪只会增加调试成本。我一般会按controller / service / mapper / entity / dto分层接口统一返回{code, msg, data}结构方便 Android 端解析。2.2 核心表结构与字段说明物流系统的表不用多但几张核心表必须设计对。下面是我实际用的建表语句MySQL 8.0 可直接执行。-- 用户表区分角色物流系统里角色决定能看到哪些运单 CREATE TABLE sys_user ( id BIGINT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) NOT NULL UNIQUE COMMENT 登录名, password VARCHAR(100) NOT NULL COMMENT BCrypt 加密后的密码, real_name VARCHAR(50) COMMENT 真实姓名, phone VARCHAR(20) COMMENT 联系电话, role TINYINT NOT NULL DEFAULT 3 COMMENT 1管理员 2司机 3客户, create_time DATETIME DEFAULT CURRENT_TIMESTAMP ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; -- 运单表整个系统的核心status 字段驱动所有业务流转 CREATE TABLE waybill ( id BIGINT PRIMARY KEY AUTO_INCREMENT, bill_no VARCHAR(32) NOT NULL UNIQUE COMMENT 运单号业务唯一, sender_id BIGINT NOT NULL COMMENT 寄件人 user_id, receiver_id BIGINT NOT NULL COMMENT 收件人 user_id, driver_id BIGINT COMMENT 承运司机 user_id, goods_name VARCHAR(100) COMMENT 货物名称, weight DECIMAL(10,2) COMMENT 重量 kg, status TINYINT NOT NULL DEFAULT 0 COMMENT 0待揽收 1运输中 2已签收 3异常, send_addr VARCHAR(200) COMMENT 寄件地址, recv_addr VARCHAR(200) COMMENT 收件地址, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, INDEX idx_driver (driver_id), INDEX idx_status (status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; -- 运单轨迹表每次状态变更写一条方便客户端展示物流详情 CREATE TABLE waybill_trace ( id BIGINT PRIMARY KEY AUTO_INCREMENT, waybill_id BIGINT NOT NULL, status TINYINT NOT NULL, remark VARCHAR(200) COMMENT 如已到达杭州中转站, operator_id BIGINT COMMENT 操作人, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, INDEX idx_waybill (waybill_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;waybill.status是整套系统的状态机核心所有接口的权限校验和业务分支都围绕它展开。waybill_trace单独拆表而不是在运单表里堆字段是因为轨迹是只增不改的流水拆开后查询详情时按waybill_id走索引性能稳定。bill_no加唯一索引防止客户端重复提交产生重复运单这是物流系统里最常见的脏数据来源。注意password字段长度给到 100因为 BCrypt 加密后的串有 60 位留足余量。别用 MD5现在面试官看到 MD5 存密码基本会扣分。3. 服务端接口实现运单创建与状态流转3.1 运单创建接口的完整实现Android 端提交运单后服务端要做三件事生成唯一运单号、落库运单、写第一条轨迹。下面用 Spring Boot 写一个最小可用版本。RestController RequestMapping(/api/waybill) public class WaybillController { Autowired private WaybillService waybillService; // 创建运单Android 端揽收页面调用 PostMapping(/create) public ResultWaybillVO create(RequestBody Valid WaybillCreateDTO dto, RequestHeader(userId) Long userId) { // userId 从登录态透传不信任客户端传的 senderId WaybillVO vo waybillService.createWaybill(dto, userId); return Result.success(vo); } // 司机更新运单状态运输中/已签收都走这个接口 PostMapping(/updateStatus) public ResultVoid updateStatus(RequestBody Valid StatusUpdateDTO dto, RequestHeader(userId) Long userId) { waybillService.updateStatus(dto, userId); return Result.success(null); } }Service 层是业务重点状态流转必须做前置校验不能客户端传什么就改什么。Service public class WaybillServiceImpl implements WaybillService { Autowired private WaybillMapper waybillMapper; Autowired private WaybillTraceMapper traceMapper; Override Transactional(rollbackFor Exception.class) public WaybillVO createWaybill(WaybillCreateDTO dto, Long userId) { Waybill wb new Waybill(); // 运单号时间戳 4 位随机生产环境建议用雪花算法 wb.setBillNo(System.currentTimeMillis() String.format(%04d, ThreadLocalRandom.current().nextInt(10000))); wb.setSenderId(userId); wb.setReceiverId(dto.getReceiverId()); wb.setGoodsName(dto.getGoodsName()); wb.setWeight(dto.getWeight()); wb.setSendAddr(dto.getSendAddr()); wb.setRecvAddr(dto.getRecvAddr()); wb.setStatus(0); // 初始待揽收 waybillMapper.insert(wb); // 同步写轨迹保证详情页有第一条记录 WaybillTrace trace new WaybillTrace(); trace.setWaybillId(wb.getId()); trace.setStatus(0); trace.setRemark(运单已创建等待揽收); trace.setOperatorId(userId); traceMapper.insert(trace); return convertToVO(wb); } Override Transactional(rollbackFor Exception.class) public void updateStatus(StatusUpdateDTO dto, Long userId) { Waybill wb waybillMapper.selectById(dto.getWaybillId()); if (wb null) { throw new BizException(运单不存在); } // 只有承运司机能改自己名下的运单 if (!userId.equals(wb.getDriverId())) { throw new BizException(无权操作该运单); } // 状态只能向前不能回退 if (dto.getStatus() wb.getStatus()) { throw new BizException(状态流转非法); } wb.setStatus(dto.getStatus()); waybillMapper.updateById(wb); WaybillTrace trace new WaybillTrace(); trace.setWaybillId(wb.getId()); trace.setStatus(dto.getStatus()); trace.setRemark(dto.getRemark()); trace.setOperatorId(userId); traceMapper.insert(trace); } }Transactional保证运单更新和轨迹写入要么都成功要么都回滚这是物流系统里不能省的一步。状态校验里dto.getStatus() wb.getStatus()挡住了回退和重复提交实际项目里还要加乐观锁版本号防止两个司机同时操作同一单。运单号生成用时间戳加随机数只是演示并发高时会有碰撞风险生产环境换成雪花算法或数据库序列。3.2 接口参数与返回结构约定Android 端和服务端联调最容易扯皮的就是字段命名和空值处理。我一般会固定一套约定写进接口文档里。字段类型说明是否必填billNoString运单号服务端生成返回时必带senderIdLong寄件人 ID从登录态取创建时服务端填充receiverIdLong收件人 ID是goodsNameString货物名称是weightBigDecimal重量单位 kg是statusInteger0-3 状态码返回时必带createTimeStringyyyy-MM-dd HH:mm:ss返回时必带返回统一用ResultTcode0表示成功非 0 时msg给用户可读的提示。Android 端拿到code ! 0直接弹 Toast不要自己拼错误文案否则两端文案不一致排查时很痛苦。提示接口测试阶段用 Postman 或 Apifox 先把创建、改状态、查详情三条链路跑通再让 Android 端接入。服务端接口测试这个热搜词背后其实就是先把契约固定下来别让客户端猜。4. Android 端对接服务端接口的关键步骤4.1 网络层用 Retrofit OkHttp 的最小配置Android 端不需要搞太复杂Retrofit 加 OkHttp 足够。下面是一个可直接抄的配置。// 网络请求单例全局复用 OkHttpClient object ApiClient { private const val BASE_URL http://10.0.2.2:8080/ // 模拟器访问宿主机 private val okHttp OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(15, TimeUnit.SECONDS) .addInterceptor { chain - // 登录后把 userId 塞进请求头服务端据此鉴权 val request chain.request().newBuilder() .addHeader(userId, UserManager.userId.toString()) .build() chain.proceed(request) } .build() val api: WaybillApi by lazy { Retrofit.Builder() .baseUrl(BASE_URL) .client(okHttp) .addConverterFactory(GsonConverterFactory.create()) .build() .create(WaybillApi::class.java) } }10.0.2.2是 Android 模拟器访问宿主机 localhost 的固定地址真机调试要换成电脑局域网 IP。userId放请求头而不是请求体是为了让服务端在拦截器里统一做登录校验业务代码不用每个接口都传。超时时间设 10 秒和 15 秒物流系统里图片上传少这个值够用如果后面加签收拍照读超时要调到 30 秒。4.2 运单列表页的数据加载与分页列表页是 Android 端最常翻车的地方尤其是分页和下拉刷新。核心逻辑是维护page和hasMore两个变量。class WaybillListViewModel : ViewModel() { private var page 1 private var hasMore true val waybillList MutableLiveDataListWaybill() fun loadWaybills(isRefresh: Boolean) { if (isRefresh) { page 1 hasMore true } if (!hasMore) return viewModelScope.launch { try { val resp ApiClient.api.listWaybills(page, 10) if (resp.code 0) { val newData resp.data ?: emptyList() // 刷新时替换加载更多时追加 val current if (isRefresh) emptyList() else waybillList.value.orEmpty() waybillList.value current newData hasMore newData.size 10 page } } catch (e: Exception) { // 网络异常时保留已有数据只提示 ToastHelper.show(网络异常请稍后重试) } } } }hasMore判断用返回条数是否等于页大小简单但有效。刷新时重置page和hasMore避免下拉刷新后数据错乱。异常处理里不要清空列表否则用户滑到一半网络抖动页面直接变白体验很差。这个逻辑在物流系统里尤其重要司机在路上的网络本来就不稳定。5. 联调避坑物流系统里最容易翻车的 5 个点5.1 运单状态回退导致数据错乱现象司机误点「已签收」后想改回「运输中」客户端直接调更新接口服务端没拦运单状态回退轨迹表里出现两条矛盾记录。原因更新接口只校验了权限没校验状态流转方向。解决在 Service 层加状态机校验只允许0→1→2或0→3任何回退请求直接抛业务异常。轨迹表只追加不修改历史记录永远可追溯。5.2 Android 端重复提交产生重复运单现象揽收页面网络慢用户连点两次提交服务端生成两条运单号不同的记录。原因客户端没做按钮防抖服务端没做幂等。解决客户端提交后立即禁用按钮服务端用bill_no唯一索引兜底插入冲突时返回已有运单而不是报错。更稳的做法是客户端生成一个requestId服务端用 Redis 做短时幂等。5.3 时间字段时区不一致现象服务端返回createTime是 UTC 时间Android 端直接展示用户看到的时间比实际早 8 小时。原因MySQL 连接串没配时区Jackson 序列化没指定格式。解决JDBC URL 加serverTimezoneAsia/Shanghai实体类时间字段加JsonFormat(pattern yyyy-MM-dd HH:mm:ss, timezone GMT8)。两端约定统一用东八区别在客户端做时区转换。5.4 列表分页在数据变更后错位现象用户在第一页看到 10 条翻到第二页时后台新增了一条运单第二页第一条和第一页最后一条重复。原因基于 offset 的分页在数据插入后会偏移。解决物流系统列表按create_time desc, id desc排序分页用id lastId的游标方式而不是limit offset。数据量大时游标分页性能也更好。5.5 服务端接口返回 null 导致 Android 端崩溃现象运单详情页某个字段服务端没查到返回 nullAndroid 端直接.length或.trim()触发空指针。原因两端对空值处理约定不一致。解决服务端返回前统一做空值兜底字符串给空串、集合给空数组、对象给默认值Android 端用 Kotlin 可空类型加?.和?:处理。别指望一端全兜住两端都要防。6. 用状态机 轨迹表把运单流转做成可验证的闭环前面把创建和更新讲完了但物流系统真正体现功底的是「怎么证明运单状态没被改坏」。我一般会在服务端加一个状态机校验器把合法流转路径集中管理而不是散落在各个 if 里。public enum WaybillStatus { PENDING(0), IN_TRANSIT(1), SIGNED(2), EXCEPTION(3); private final int code; WaybillStatus(int code) { this.code code; } // 定义合法流转待揽收可到运输中或异常运输中可到签收或异常 private static final MapInteger, SetInteger TRANSITIONS Map.of( 0, Set.of(1, 3), 1, Set.of(2, 3), 2, Set.of(), 3, Set.of(1) ); public static boolean canTransfer(int from, int to) { return TRANSITIONS.getOrDefault(from, Set.of()).contains(to); } }Service 里更新状态前调WaybillStatus.canTransfer(wb.getStatus(), dto.getStatus())不合法直接拒绝。这样以后加「退回」「改址」等新状态只改枚举里的映射表不用翻遍业务代码。轨迹表则保证每次变更都有记录客户端查详情时按时间正序展示用户看到的就是完整物流链路。验证方法也简单写一个 JUnit 测试把 0→1、1→2、2→1、0→2 这些路径都跑一遍断言只有合法路径通过。这个测试用例在答辩或交付时比任何文档都有说服力。提示状态机映射表用Map.of初始化时注意不可变如果后续要动态扩展换成ConcurrentHashMap并在启动时加载。我自己踩过最深的坑是早期把状态判断写在 Controller 里后来加了一个「异常件重新派送」的需求改了三处代码还漏了一处导致线上出现签收单被重新激活。从那以后凡是状态流转一律收进枚举和 ServiceController 只做参数接收。这套方案不复杂但能挡住物流系统里八成以上的数据一致性问题。希望帮到你。本文还有配套的精品资源点击获取
简介这是一套面向Java Web与Android初学者及课程设计者的物流管理系统完整源码采用JSP、Servlet、Android与Ajax异步交互技术实现数据库选用开源MySQL服务端按表现层、业务层、数据访问层分层设计表现层基于MVC结构业务层为每个模块提供独立接口与实现类便于应对业务变更并适配不同数据库。压缩包共899个文件约9.48MB其中47个java源文件与47个class文件构成核心业务逻辑32个jsp页面与116个js脚本支撑前后端交互另有大量gif、png、jpg图片资源及css样式、jar依赖包整体结构完整。目前已有506人学习下载。读者可从中获得一套可直接运行的物流管理项目参考理解Servlet与Ajax协同、分层架构与数据库访问的落地方式适合作为毕业设计、课程作业或Java Web入门练手素材。1. 物流管理系统从零落地Android 端加 Java 服务端到底怎么搭很多做毕设或接私活的兄弟拿到「基于 Android 的物流管理系统服务端 Java 实现」这个题目时第一反应是去搜一套现成源码跑起来交差。但真到答辩或上线面试官或甲方一句「你这个运单状态流转怎么保证不丢单」就能把人问住。这个标题背后其实是一套典型的 C/S 架构Android 客户端负责快递员揽收、司机运输、客户查件这些移动场景Java 服务端负责订单、运单、车辆、用户权限和状态机。它适合两类人——想用真实业务练手 Android Spring Boot 全栈的学生以及需要快速搭一套内部物流调度工具的小团队。核心难点不在界面而在服务端接口设计、运单状态一致性和两端数据同步。下面按我实际搭过的一套方案把选型、建表、接口、联调和踩坑讲透。2. 服务端技术选型与数据库表结构设计2.1 为什么选 Spring Boot MyBatis 而不是纯 Servlet标题写的是「服务端 Java 实现」范围很宽。常见做法是用 Spring Boot 起一个单体服务配 MyBatis 做持久层MySQL 存业务数据。理由很直接物流系统里运单、车辆、网点、用户之间有大量关联查询MyBatis 手写 SQL 对复杂条件筛选和分页更可控Spring Boot 内嵌 Tomcat打包成 jar 直接java -jar就能跑部署到一台 2 核 4G 的云主机上足够支撑小规模使用。如果团队后续要拆微服务Spring Boot 的模块划分也容易迁移。不推荐一上来就上 Spring Cloud物流管理系统的并发量通常没到那个级别注册中心、网关、链路追踪只会增加调试成本。我一般会按controller / service / mapper / entity / dto分层接口统一返回{code, msg, data}结构方便 Android 端解析。2.2 核心表结构与字段说明物流系统的表不用多但几张核心表必须设计对。下面是我实际用的建表语句MySQL 8.0 可直接执行。-- 用户表区分角色物流系统里角色决定能看到哪些运单 CREATE TABLE sys_user ( id BIGINT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) NOT NULL UNIQUE COMMENT 登录名, password VARCHAR(100) NOT NULL COMMENT BCrypt 加密后的密码, real_name VARCHAR(50) COMMENT 真实姓名, phone VARCHAR(20) COMMENT 联系电话, role TINYINT NOT NULL DEFAULT 3 COMMENT 1管理员 2司机 3客户, create_time DATETIME DEFAULT CURRENT_TIMESTAMP ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; -- 运单表整个系统的核心status 字段驱动所有业务流转 CREATE TABLE waybill ( id BIGINT PRIMARY KEY AUTO_INCREMENT, bill_no VARCHAR(32) NOT NULL UNIQUE COMMENT 运单号业务唯一, sender_id BIGINT NOT NULL COMMENT 寄件人 user_id, receiver_id BIGINT NOT NULL COMMENT 收件人 user_id, driver_id BIGINT COMMENT 承运司机 user_id, goods_name VARCHAR(100) COMMENT 货物名称, weight DECIMAL(10,2) COMMENT 重量 kg, status TINYINT NOT NULL DEFAULT 0 COMMENT 0待揽收 1运输中 2已签收 3异常, send_addr VARCHAR(200) COMMENT 寄件地址, recv_addr VARCHAR(200) COMMENT 收件地址, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, INDEX idx_driver (driver_id), INDEX idx_status (status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; -- 运单轨迹表每次状态变更写一条方便客户端展示物流详情 CREATE TABLE waybill_trace ( id BIGINT PRIMARY KEY AUTO_INCREMENT, waybill_id BIGINT NOT NULL, status TINYINT NOT NULL, remark VARCHAR(200) COMMENT 如已到达杭州中转站, operator_id BIGINT COMMENT 操作人, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, INDEX idx_waybill (waybill_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;waybill.status是整套系统的状态机核心所有接口的权限校验和业务分支都围绕它展开。waybill_trace单独拆表而不是在运单表里堆字段是因为轨迹是只增不改的流水拆开后查询详情时按waybill_id走索引性能稳定。bill_no加唯一索引防止客户端重复提交产生重复运单这是物流系统里最常见的脏数据来源。注意password字段长度给到 100因为 BCrypt 加密后的串有 60 位留足余量。别用 MD5现在面试官看到 MD5 存密码基本会扣分。3. 服务端接口实现运单创建与状态流转3.1 运单创建接口的完整实现Android 端提交运单后服务端要做三件事生成唯一运单号、落库运单、写第一条轨迹。下面用 Spring Boot 写一个最小可用版本。RestController RequestMapping(/api/waybill) public class WaybillController { Autowired private WaybillService waybillService; // 创建运单Android 端揽收页面调用 PostMapping(/create) public ResultWaybillVO create(RequestBody Valid WaybillCreateDTO dto, RequestHeader(userId) Long userId) { // userId 从登录态透传不信任客户端传的 senderId WaybillVO vo waybillService.createWaybill(dto, userId); return Result.success(vo); } // 司机更新运单状态运输中/已签收都走这个接口 PostMapping(/updateStatus) public ResultVoid updateStatus(RequestBody Valid StatusUpdateDTO dto, RequestHeader(userId) Long userId) { waybillService.updateStatus(dto, userId); return Result.success(null); } }Service 层是业务重点状态流转必须做前置校验不能客户端传什么就改什么。Service public class WaybillServiceImpl implements WaybillService { Autowired private WaybillMapper waybillMapper; Autowired private WaybillTraceMapper traceMapper; Override Transactional(rollbackFor Exception.class) public WaybillVO createWaybill(WaybillCreateDTO dto, Long userId) { Waybill wb new Waybill(); // 运单号时间戳 4 位随机生产环境建议用雪花算法 wb.setBillNo(System.currentTimeMillis() String.format(%04d, ThreadLocalRandom.current().nextInt(10000))); wb.setSenderId(userId); wb.setReceiverId(dto.getReceiverId()); wb.setGoodsName(dto.getGoodsName()); wb.setWeight(dto.getWeight()); wb.setSendAddr(dto.getSendAddr()); wb.setRecvAddr(dto.getRecvAddr()); wb.setStatus(0); // 初始待揽收 waybillMapper.insert(wb); // 同步写轨迹保证详情页有第一条记录 WaybillTrace trace new WaybillTrace(); trace.setWaybillId(wb.getId()); trace.setStatus(0); trace.setRemark(运单已创建等待揽收); trace.setOperatorId(userId); traceMapper.insert(trace); return convertToVO(wb); } Override Transactional(rollbackFor Exception.class) public void updateStatus(StatusUpdateDTO dto, Long userId) { Waybill wb waybillMapper.selectById(dto.getWaybillId()); if (wb null) { throw new BizException(运单不存在); } // 只有承运司机能改自己名下的运单 if (!userId.equals(wb.getDriverId())) { throw new BizException(无权操作该运单); } // 状态只能向前不能回退 if (dto.getStatus() wb.getStatus()) { throw new BizException(状态流转非法); } wb.setStatus(dto.getStatus()); waybillMapper.updateById(wb); WaybillTrace trace new WaybillTrace(); trace.setWaybillId(wb.getId()); trace.setStatus(dto.getStatus()); trace.setRemark(dto.getRemark()); trace.setOperatorId(userId); traceMapper.insert(trace); } }Transactional保证运单更新和轨迹写入要么都成功要么都回滚这是物流系统里不能省的一步。状态校验里dto.getStatus() wb.getStatus()挡住了回退和重复提交实际项目里还要加乐观锁版本号防止两个司机同时操作同一单。运单号生成用时间戳加随机数只是演示并发高时会有碰撞风险生产环境换成雪花算法或数据库序列。3.2 接口参数与返回结构约定Android 端和服务端联调最容易扯皮的就是字段命名和空值处理。我一般会固定一套约定写进接口文档里。字段类型说明是否必填billNoString运单号服务端生成返回时必带senderIdLong寄件人 ID从登录态取创建时服务端填充receiverIdLong收件人 ID是goodsNameString货物名称是weightBigDecimal重量单位 kg是statusInteger0-3 状态码返回时必带createTimeStringyyyy-MM-dd HH:mm:ss返回时必带返回统一用ResultTcode0表示成功非 0 时msg给用户可读的提示。Android 端拿到code ! 0直接弹 Toast不要自己拼错误文案否则两端文案不一致排查时很痛苦。提示接口测试阶段用 Postman 或 Apifox 先把创建、改状态、查详情三条链路跑通再让 Android 端接入。服务端接口测试这个热搜词背后其实就是先把契约固定下来别让客户端猜。4. Android 端对接服务端接口的关键步骤4.1 网络层用 Retrofit OkHttp 的最小配置Android 端不需要搞太复杂Retrofit 加 OkHttp 足够。下面是一个可直接抄的配置。// 网络请求单例全局复用 OkHttpClient object ApiClient { private const val BASE_URL http://10.0.2.2:8080/ // 模拟器访问宿主机 private val okHttp OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(15, TimeUnit.SECONDS) .addInterceptor { chain - // 登录后把 userId 塞进请求头服务端据此鉴权 val request chain.request().newBuilder() .addHeader(userId, UserManager.userId.toString()) .build() chain.proceed(request) } .build() val api: WaybillApi by lazy { Retrofit.Builder() .baseUrl(BASE_URL) .client(okHttp) .addConverterFactory(GsonConverterFactory.create()) .build() .create(WaybillApi::class.java) } }10.0.2.2是 Android 模拟器访问宿主机 localhost 的固定地址真机调试要换成电脑局域网 IP。userId放请求头而不是请求体是为了让服务端在拦截器里统一做登录校验业务代码不用每个接口都传。超时时间设 10 秒和 15 秒物流系统里图片上传少这个值够用如果后面加签收拍照读超时要调到 30 秒。4.2 运单列表页的数据加载与分页列表页是 Android 端最常翻车的地方尤其是分页和下拉刷新。核心逻辑是维护page和hasMore两个变量。class WaybillListViewModel : ViewModel() { private var page 1 private var hasMore true val waybillList MutableLiveDataListWaybill() fun loadWaybills(isRefresh: Boolean) { if (isRefresh) { page 1 hasMore true } if (!hasMore) return viewModelScope.launch { try { val resp ApiClient.api.listWaybills(page, 10) if (resp.code 0) { val newData resp.data ?: emptyList() // 刷新时替换加载更多时追加 val current if (isRefresh) emptyList() else waybillList.value.orEmpty() waybillList.value current newData hasMore newData.size 10 page } } catch (e: Exception) { // 网络异常时保留已有数据只提示 ToastHelper.show(网络异常请稍后重试) } } } }hasMore判断用返回条数是否等于页大小简单但有效。刷新时重置page和hasMore避免下拉刷新后数据错乱。异常处理里不要清空列表否则用户滑到一半网络抖动页面直接变白体验很差。这个逻辑在物流系统里尤其重要司机在路上的网络本来就不稳定。5. 联调避坑物流系统里最容易翻车的 5 个点5.1 运单状态回退导致数据错乱现象司机误点「已签收」后想改回「运输中」客户端直接调更新接口服务端没拦运单状态回退轨迹表里出现两条矛盾记录。原因更新接口只校验了权限没校验状态流转方向。解决在 Service 层加状态机校验只允许0→1→2或0→3任何回退请求直接抛业务异常。轨迹表只追加不修改历史记录永远可追溯。5.2 Android 端重复提交产生重复运单现象揽收页面网络慢用户连点两次提交服务端生成两条运单号不同的记录。原因客户端没做按钮防抖服务端没做幂等。解决客户端提交后立即禁用按钮服务端用bill_no唯一索引兜底插入冲突时返回已有运单而不是报错。更稳的做法是客户端生成一个requestId服务端用 Redis 做短时幂等。5.3 时间字段时区不一致现象服务端返回createTime是 UTC 时间Android 端直接展示用户看到的时间比实际早 8 小时。原因MySQL 连接串没配时区Jackson 序列化没指定格式。解决JDBC URL 加serverTimezoneAsia/Shanghai实体类时间字段加JsonFormat(pattern yyyy-MM-dd HH:mm:ss, timezone GMT8)。两端约定统一用东八区别在客户端做时区转换。5.4 列表分页在数据变更后错位现象用户在第一页看到 10 条翻到第二页时后台新增了一条运单第二页第一条和第一页最后一条重复。原因基于 offset 的分页在数据插入后会偏移。解决物流系统列表按create_time desc, id desc排序分页用id lastId的游标方式而不是limit offset。数据量大时游标分页性能也更好。5.5 服务端接口返回 null 导致 Android 端崩溃现象运单详情页某个字段服务端没查到返回 nullAndroid 端直接.length或.trim()触发空指针。原因两端对空值处理约定不一致。解决服务端返回前统一做空值兜底字符串给空串、集合给空数组、对象给默认值Android 端用 Kotlin 可空类型加?.和?:处理。别指望一端全兜住两端都要防。6. 用状态机 轨迹表把运单流转做成可验证的闭环前面把创建和更新讲完了但物流系统真正体现功底的是「怎么证明运单状态没被改坏」。我一般会在服务端加一个状态机校验器把合法流转路径集中管理而不是散落在各个 if 里。public enum WaybillStatus { PENDING(0), IN_TRANSIT(1), SIGNED(2), EXCEPTION(3); private final int code; WaybillStatus(int code) { this.code code; } // 定义合法流转待揽收可到运输中或异常运输中可到签收或异常 private static final MapInteger, SetInteger TRANSITIONS Map.of( 0, Set.of(1, 3), 1, Set.of(2, 3), 2, Set.of(), 3, Set.of(1) ); public static boolean canTransfer(int from, int to) { return TRANSITIONS.getOrDefault(from, Set.of()).contains(to); } }Service 里更新状态前调WaybillStatus.canTransfer(wb.getStatus(), dto.getStatus())不合法直接拒绝。这样以后加「退回」「改址」等新状态只改枚举里的映射表不用翻遍业务代码。轨迹表则保证每次变更都有记录客户端查详情时按时间正序展示用户看到的就是完整物流链路。验证方法也简单写一个 JUnit 测试把 0→1、1→2、2→1、0→2 这些路径都跑一遍断言只有合法路径通过。这个测试用例在答辩或交付时比任何文档都有说服力。提示状态机映射表用Map.of初始化时注意不可变如果后续要动态扩展换成ConcurrentHashMap并在启动时加载。我自己踩过最深的坑是早期把状态判断写在 Controller 里后来加了一个「异常件重新派送」的需求改了三处代码还漏了一处导致线上出现签收单被重新激活。从那以后凡是状态流转一律收进枚举和 ServiceController 只做参数接收。这套方案不复杂但能挡住物流系统里八成以上的数据一致性问题。希望帮到你。本文还有配套的精品资源点击获取
