从零自建CRM系统：FastAPI+PostgreSQL打造DeskcommCRM的实战复盘
2026/9/14 4:56:25
简介：这是一份围绕 WebMagic 的 Java 爬虫框架学习项目，面向有一定 Java 基础、希望快速上手网络数据采集的初学者，也适合用作高校课程设计与培训的参考案例。资源以 WebMagicDemo 工程为主体，覆盖 URL 收集、请求网页、解析内容、数据存储等爬虫核心环节，并演示了框架的 API 调用与配置方式，可帮助读者理解从入口调度到数据落地的完整链路。压缩包共 94 个文件，包含 28 个 Java 源码、28 个编译后的 class 文件、25 张示意图，以及 properties、xml、ini 等配置文件，整体大小 23.8MB；源码与编译产物并存，目录结构清晰，便于按模块对照学习。该项目已有 116 人学习/下载，适合用于自学和小组讨论。通过项目中的依赖配置可还原 Maven 环境，结合说明文档与博客图片，能掌握从新建工程、编写采集逻辑、处理解析结果到调试运行的完整思路，适合用作入门练习和课堂参考，也能为后续开发自己的采集工具提供直接借鉴。
1. WebMagic不是爬虫界的轰炸机，而是一套能拆开调试的四段流水线
拿到“WebMagic--Java爬虫框架学习.zip”这个资料包，最容易踩的坑不是看不懂代码，而是把压缩包里的源码导进IDE之后不知道从哪一行开始读。WebMagic的价值不在于帮你写出抓取速度最快的爬虫，而在于它把一次完整抓取拆成下载器、页面处理器、调度器和结果输出器四个独立的环节，中间用接口衔接。因此学这个框架的重心只需要放在三件事上：跑通第一条抓取链路、把Site上的参数调成目标站点能接受的样子、把结果从控制台挪进自己的数据库里。适合已经掌握Java语法、想通过一个完整项目理解爬虫生命周期的开发者，也适合后端工程师在公司内部做数据同步工具时快速落地。
2. 跑通最小抓取链路：从依赖到第一份抓取结果
2.1 依赖选择：只引Core还是连Extension一起引
WebMagic在Maven仓库里拆成几个构件，最常见的两个是webmagic-core和webmagic-extension。Core的职责是完成下载、解析、调度和输出这条主链路，只依赖HttpClient和Jsoup，没有任何Spring相关的包袱。Extension则提供了注解驱动的声明式抽取、基于XPath的@ExtractBy、以及JsonPathSelector这类便捷工具，同时把一些现成的Pipeline（比如ConsolePipeline、FilePipeline）也放了进去。
<properties> <webmagic.version>LATEST</webmagic.version> </properties> <dependencies> <dependency> <groupId>us.codecraft</groupId> <artifactId>webmagic-core</artifactId> <version>${webmagic.version}</version> </dependency> <dependency> <groupId>us.codecraft</groupId> <artifactId>webmagic-extension</artifactId> <version>${webmagic.version}</version> </dependency> </dependencies>这里把版本号写成了LATEST，实际使用中建议将它固定为你本地Nexus或Maven Central已经同步的具体版本。逻辑上webmagic-extension传递依赖了webmagic-core，所以只引Extension也能编译，但对于想搞清楚内部结构的初学者，两条都写上，IDE里跳转源码时能直接区分核心类与扩展类。导入依赖后先检查Site和Spider两个类能否被解析，这一步能过滤掉大多数因仓库未同步导致的版本问题。
2.2 准备一个可复现的本地目标页面
直接抓线上站点容易遇到反爬和页面结构变动，调试时无法确定问题出在网络上还是解析逻辑里。更稳妥的做法是在本地起一个静态HTTP服务，用自己的HTML页面作为抓取对象。这里准备一个最简列表页list.html，以及三个详情页detail1.html、detail2.html、detail3.html，放在同目录下。
<!DOCTYPE html> <html> <head><meta charset="utf-8"><title>列表</title></head> <body> <ul> <li><a href="detail1.html">商品A</a></li> <li><a href="detail2.html">商品B</a></li> <li><a href="detail3.html">商品C</a></li> </ul> </body> </html>cd /path/to/html && python3 -m http.server 8080这个命令会在8080端口把当前目录暴露为静态站点，访问http://localhost:8080/list.html能看到刚才写的列表。之所以把目标站放在本地，是因为爬虫调试的第一原则是排除网络干扰：真正的问题往往不是目标站拒绝了请求，而是解析表达式写错。本地页面还能随时改结构，用来验证不同XPath的边界情况，这是抓线上页面做不到的。
2.3 PageProcessor里写清“抓到什么”和“怎么提取”
WebMagic中所有抓取逻辑都收敛在PageProcessor接口上，它只有process(Page page)和getSite()两个抽象方法。process方法在每次下载完成后被调用，page.getHtml()返回的是结构化后的Html对象，可以直接链式调用XPath、正则和CSS选择器。下面的代码抓取列表页里的商品链接，再把链接加入待抓取队列，并提取详情页标题。
import us.codecraft.webmagic.Page; import us.codecraft.webmagic.Site; import us.codecraft.webmagic.Spider; import us.codecraft.webmagic.processor.PageProcessor; public class LocalListProcessor implements PageProcessor { private Site site = Site.me() .setRetryTimes(2) .setSleepTime(100) .setCharset("utf-8"); @Override public void process(Page page) { if (page.getUrl().regex("detail\\d+\\.html").match()) { String title = page.getHtml().xpath("//title/text()").get(); page.putField("title", title); page.putField("url", page.getUrl().toString()); } else { page.addTargetRequests( page.getHtml().xpath("//ul/li/a/@href").all() ); } } @Override public Site getSite() { return site; } public static void main(String[] args) { Spider.create(new LocalListProcessor()) .addUrl("http://localhost:8080/list.html") .thread(1) .run(); } }这段代码里有两个关键的逻辑分支：当页面URL匹配detail数字.html时执行详情解析，否则把列表页里所有a标签的href属性通过addTargetRequests塞进待抓取队列。xpath("//ul/li/a/@href").all()返回的是List，而.get()只取第一条。Spider.create(...).addUrl(...).thread(1).run()这一串链式调用中，thread(1)显式指定单线程，便于初学者观察日志中每个请求的顺序。如果list.html里的链接是相对路径，WebMagic会自动拼接为绝对URL后再进入调度器，这是框架内部完成的，不需要自己写URL拼装。
2.4 从控制台观察签名式输出
上面代码没有显式添加Pipeline，默认情况下结果会通过ConsolePipeline打印到控制台。运行main方法后能看到类似下面的输出结构。
[main] INFO us.codecraft.webmagic.Spider - Spider localhost started! [main] INFO us.codecraft.webmagic.Spider - page https://localhost:8080/list.html [main] INFO us.codecraft.webmagic.Spider - extract success: {"title":"商品A","url":"http://localhost:8080/detail1.html"}日志中extract success后面的JSON片段就是page.putField写入的字段，它们会被统一收集到ResultItems对象里，再依次交给所有注册的Pipeline。这一步跑通后，你已经理解了WebMagic最核心的“下载-解析-输出”循环：Downloader抓取HTML，Html解析器把内容变成可查询的结构，PageProcessor决定哪些内容进入结果集、哪些链接进入下一步队列。后续所有扩展都围绕这个循环做文章。
3. 让抓取变稳：Site参数、线程数与异常处理
3.1 Site 上那批“看起来不用改”的参数
Site对象管理的是单个站点维度上的HTTP配置。实际业务中一个爬虫项目往往只针对一个域名的有限范围，因此把UserAgent、超时、重试、编码这些参数统一收敛到一个Site实例里，比散落在各个请求里更利于维护。下面是需要重点关注的一组参数：
| 参数名 | 默认值 | 推荐值区间 | 说明 |
|---|---|---|---|
setTimeout | 5000 | 3000-10000 | 连接与读取超时，单位毫秒，移动网络下调大 |
setRetryTimes | 0 | 2-3 | 下载失败后的重试次数，超过后放弃该请求 |
setRetrySleepTime | 1000 | 1000-3000 | 两次重试之间的间隔，防止快速重试被封 |
setSleepTime | 0 | 100-500 | 每次下载完成后的休眠时间，静态页面可以设0 |
setCharset | 空 | utf-8/gbk | 页面编码，不设置时走内容嗅探 |
setUserAgent | WebMagic | 具体浏览器UA | 有些站点会拦截空UA或默认UA |
setAcceptStatCode | 200 | 200, 404 | 把指定状态码视为正常结果继续处理 |
需要特别说明的是setAcceptStatCode。默认情况下只有HTTP 200会被当作成功下载，但某些站点的反爬策略是返回404页面但内容正常，或者在页面未找到时返回200且附带提示文案。这个参数的意义是控制Downloader的判定逻辑，而不是影响PageProcessor内部的解析。另一种常见误用是setSleepTime和setRetrySleepTime混为一谈，前者是每个请求之间的间隔，后者是重试动作之间的间隔，两个都偏小时爬取速度很快，代价是一旦触发限流会连续吃多个错误码。
3.2 下载线程数不是越大越快
Spider.thread(n)是下载器并发线程数，默认1。初学者容易把它类比为线程池大小，认为调成10或者20吞吐量就能线性增长，但爬虫的场景和普通RPC服务有一个本质区别：它大部分时间阻塞在等待目标站点响应环节，属于IO密集型任务。对单机抓取来说，线程数从1提到5通常能明显提升吞吐，但继续增加到10个以上时，收益迅速衰减，取而代之的是两个副作用。
第一个副作用是请求频率呈线性放大。如果目标站点自身性能一般，10个线程并发请求会让日志中出现大量ConnectTimeout，这是目标服务端已经扛不住载荷的表现，此时线程数越大，整体任务完成得反而越慢。第二个副作用是PageProcessor内的共享状态被多线程并发访问。框架会为每个线程复用同一个PageProcessor实例，如果在process方法里写了一个实例字段用来累加计数，线程之间会互相覆盖，导致结果数量对不上。
// 错误示例：多线程下count结果不确定 private int count = 0; @Override public void process(Page page) { count++; }正确的做法是把统计信息放在Pipeline里做聚合，或者用page.putField("_index", requestIndex)让每个请求带上序号，在输出端统一处理。线程数上限的合理判断依据是：观察日志中一个请求从开始下载到进入process处理的平均耗时，如果绝大多数时间消耗在网络等待上，那当前线程数还有上调空间；如果CPU占用已经吃满，说明页面解析逻辑过重，优先去优化XPath和正则，而不是继续加线程。
3.3 重试与下载延迟的配合策略
setRetryTimes只处理下载阶段的异常，不负责解析阶段的异常。也就是说，页面下载成功后进入process方法，哪怕解析抛出了运行时异常，框架也不会自动重试这个请求，这是因为解析失败往往意味着页面结构与预期不符，重试同一份HTML也不会带来不同结果。理解这条边界后，重试参数的调整策略就清晰了。
常见做法是把重试次数设置为2到3次，配合setRetrySleepTime的间隔用来抵抗瞬时网络波动。这两个参数的作用域是“请求”，不是“站点”，因此重试只针对失败的那个Request，不影响队列里其他等待中的URL。调试时如果发现重试没有生效，先检查请求是否是真的下载失败——用一个故意不存在的端口启动本地服务，可以看到重试日志会连续输出多条download error，这是验证重试机制最快的方法。
3.4 编码不对：setCharset与页面声明的优先级
WebMagic在解析页面时会先读取HTTP头上Content-Type声明的charset，如果响应头没有声明，再去读取HTML中meta标签的charset，最后才轮到底层HttpClient的内容嗅探。当Site上手动设置了setCharset时，这个值会覆盖响应头和meta的声明。这条规则的实用价值在于：目标站点响应头声明的是ISO-8859-1但实际页面是GBK编码时，直接在Site里指定setCharset("gbk")能绕开错误的响应头。
private Site site = Site.me() .setCharset("gbk") .setTimeOut(5000);如果设置了charset后仍然乱码，问题通常不在编码声明的优先级上，而是页面本身是UTF-8但HTTP头强制转了码，此时可以尝试不调用setCharset，让框架按照HTML中的meta标签自动嗅探。遇到编码问题先抓取页面原始字节流的前两KB，用new String(bytes, "gbk")手动验证，比反复改配置快得多。
4. 把结果交出去：Pipeline 与抓取结果校验
4.1 自定义Pipeline：解耦“抓取”与“存储”
Pipeline接口只有一个process(ResultItems resultItems, Task task)方法。ResultItems里保存的就是PageProcessor通过putField写入的字段，Task则代表当前Spider实例。默认的ConsolePipeline在控制台打印结果，FilePipeline把结果按URL的hash值分散写入磁盘文件。实际项目中更常见的做法是实现自己的Pipeline，把结果批量写入数据库。
4.2 一个可以落地的批量MySQL写入器
public class MysqlPipeline implements Pipeline { private final List<Map<String, Object>> buffer = new ArrayList<>(); private static final int BATCH_SIZE = 50; @Override public synchronized void process(ResultItems resultItems, Task task) { Map<String, Object> item = new HashMap<>(); item.put("title", resultItems.get("title")); item.put("url", resultItems.get("url")); buffer.add(item); if (buffer.size() >= BATCH_SIZE) { flush(); } } private void flush() { // 批量执行 INSERT INTO tbl (title,url) VALUES (?,?) buffer.clear(); } }这个Pipeline里的synchronized修饰是有意为之：Spider.thread(5)开启多线程后，所有下载线程会把结果同时提交到同一个Pipeline实例，不加锁的情况下ArrayList会并发写坏。BATCH_SIZE设成50意味着每凑够50条才落一次库，配合PreparedStatement的批处理能显著减少数据库连接开销。需要说明的是，resultItems.get("title")可能返回null，比如列表页请求也会被传入Pipeline，此时需要主动判断resultItems.get("url")是否存在于目标字段集合中。
4.3 用总数差定位丢失数据
抓取完成后验证数据完整性，最直接的方法是把Pipeline中超时未flush的剩余数据手动写入一次，然后对比数据库中条数与目标页面上的条目数。如果数据库少了几条，优先排查PageProcessor里xpath(...).get()是不是只取了第一条；如果字段存在但内容为null，去检查页面结构里该字段对应的标签是否真的渲染出来了。校验逻辑可以放到Pipeline的最后一个批处理中实现，不额外增加拦截器。
本文还有配套的精品资源，点击获取