在电商与物流高度融合的当下，快递查询系统已成为电商平台、物流企业不可或缺的核心功能。本文将手把手演示如何使用Java从零构建一个支持多快递公司查询的物流跟踪系统，涵盖接口设计、第三方API集成、数据展示等完整开发流程，并提供可直接运行的代码示例。

一、项目需求与技术选型

1. 核心功能需求

• 快递单号查询：输入单号后返回物流轨迹信息（如“已揽件”“运输中”）。
• 支持多快递公司：覆盖主流快递公司（如顺丰、圆通、中通）。
• 异常处理：处理单号无效、API调用失败等场景。

2. 技术栈选择

• 开发框架：Spring Boot（简化配置与快速开发）
• HTTP请求：Apache HttpClient（调用第三方API）
• JSON解析：Jackson（处理API返回数据）
• 数据库：可选MySQL（用于存储用户查询记录）

二、项目初始化

1. 创建Maven项目

使用IDEA或Eclipse创建Spring Boot项目，添加以下依赖：

xml

编辑

<dependencies>

    <!-- Spring Boot Web -->

    <dependency>

        <groupId>org.springframework.boot</groupId>

        <artifactId>spring-boot-starter-web</artifactId>

    </dependency>

    <!-- HTTP请求工具 -->

    <dependency>

        <groupId>org.apache.httpcomponents</groupId>

        <artifactId>httpclient</artifactId>

        <version>4.5.13</version>

    </dependency>

    <!-- JSON解析 -->

    <dependency>

        <groupId>com.fasterxml.jackson.core</groupId>

        <artifactId>jackson-databind</artifactId>

        <version>2.13.3</version>

    </dependency>

</dependencies>

2. 项目结构设计

text

编辑

src/main/java

├── com.example.logistics

│   ├── controller      // 接收HTTP请求

│   ├── service         // 业务逻辑层

│   ├── config          // 配置类（如API密钥）

│   └── model           // 数据模型类

三、核心代码实现

1. 第三方API对接

以快递100为例（需注册获取API密钥）：

java

编辑

import org.apache.http.client.methods.CloseableHttpResponse;

import org.apache.http.client.methods.HttpGet;

import org.apache.http.impl.client.CloseableHttpClient;

import org.apache.http.impl.client.HttpClients;

import org.apache.http.util.EntityUtils;

 

public class KdiyClient {

    private static final String API_URL = "https://www.kdiy.cn/api/v1/track";

    private static final String API_KEY = "your_api_key"; // 替换为实际密钥

 

    public String query(String companyCode, String trackingNumber) {

        try (CloseableHttpClient client = HttpClients.createDefault()) {

            String url = API_URL + "?key=" + API_KEY + "&type=" + companyCode + "&postid=" + trackingNumber;

            HttpGet request = new HttpGet(url);

            CloseableHttpResponse response = client.execute(request);

            return EntityUtils.toString(response.getEntity(), "UTF-8");

        } catch (Exception e) {

            throw new RuntimeException("API调用失败", e);

        }

    }

}

2. 数据模型定义

java

编辑

// 物流轨迹信息

public class LogisticsTrack {

    private String time;          // 时间

    private String status;        // 状态描述

    private String location;      // 位置

 

    // Getter/Setter省略

}

 

// 查询响应结果

public class LogisticsResponse {

    private String company;       // 快递公司名称

    private List<LogisticsTrack> tracks; // 物流轨迹列表

 

    // Getter/Setter省略

}

3. 服务层逻辑

java

编辑

import com.fasterxml.jackson.databind.ObjectMapper;

 

public class LogisticsService {

    private KdiyClient kdiyClient = new KdiyClient();

    private ObjectMapper objectMapper = new ObjectMapper();

 

    public LogisticsResponse getLogisticsInfo(String companyCode, String trackingNumber) {

        String jsonResult = kdiyClient.query(companyCode, trackingNumber);

        try {

            return objectMapper.readValue(jsonResult, LogisticsResponse.class);

        } catch (Exception e) {

            throw new RuntimeException("数据解析失败", e);

        }

    }

}

4. 控制器层

java

编辑

import org.springframework.web.bind.annotation.*;

 

@RestController

@RequestMapping("/api/track")

public class LogisticsController {

    private LogisticsService logisticsService = new LogisticsService();

 

    @GetMapping("/{companyCode}/{trackingNumber}")

    public LogisticsResponse track(

            @PathVariable String companyCode,

            @PathVariable String trackingNumber) {

        return logisticsService.getLogisticsInfo(companyCode, trackingNumber);

    }

}

四、功能扩展与优化

1. 支持多快递公司

维护快递公司编码映射表（如顺丰：SF，圆通：YTO），可在application.properties中配置：

properties

编辑

kdiy.company.sf=SF

kdiy.company.yto=YTO

2. 异常处理与日志记录

• 单号无效：返回自定义错误信息（如“未找到该快递单号”）。
• API限流：通过Redis缓存高频查询结果，降低API调用频率。
• 日志记录：使用Logback记录查询请求与错误详情。

3. 前端页面展示

集成Thymeleaf模板，构建简单查询页面：

html

预览

<!-- src/main/resources/templates/index.html -->

<!DOCTYPE html>

<html>

<head>

    <title>快递查询</title>

</head>

<body>

    <h1>请输入快递单号</h1>

    <form action="/search" method="get">

        快递公司: <input type="text" name="company"><br/>

        单号: <input type="text" name="trackingNumber"><br/>

        <input type="submit" value="查询">

    </form>

</body>

</html>

五、测试与部署

1. 单元测试

使用JUnit测试核心逻辑：

java

编辑

import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.*;

 

public class LogisticsServiceTest {

    @Test

    public void testQuery() {

        LogisticsService service = new LogisticsService();

        LogisticsResponse response = service.getLogisticsInfo("YTO", "YT123456789CN");

        assertNotNull(response.getTracks());

    }

}

2. 部署到云服务器

• 打包为JAR文件：mvn clean package
• 使用Docker容器化部署：

dockerfile

编辑

FROM openjdk:8-jdk-alpine

COPY target/logistics-system.jar app.jar

ENTRYPOINT ["java", "-jar", "app.jar"]

六、总结与扩展方向

通过本文的实战代码，您已掌握如何构建一个基础的Java快递查询系统。后续可进一步扩展：

• 电子面单生成功能：集成快递公司API生成发货单。
• 多平台订单同步：对接淘宝、京东等电商平台订单数据。
• AI预测物流时效：基于历史数据训练模型，预估送达时间。

立即动手实践，将您的物流查询系统部署到生产环境，为用户提供高效、透明的物流服务！