简介：提供一套面向计算机相关专业（软件工程、区块链、物联网等）毕业设计的基于区块链的文档交易系统完整源码包，适合作为高分开题、毕设或课设的参考实现。压缩包共180个文件，容量仅8.43MB，核心代码以55个Java文件、18个Vue文件及23个JavaScript文件构成，覆盖后端服务、前端交互与智能合约逻辑，此外还包含21个Word文档（项目报告、部署手册）和若干PNG图片，便于查阅设计思路与界面效果。目前已有79人学习浏览，代码经过测试可运行，并附带部署文档，降低环境搭建门槛。项目不仅演示了区块链在文档版权交易中的落地流程，还具备可修改和扩展的灵活性，适合在校学生直接用于毕业设计演示或在此基础上深化区块链应用研究。
1. 从一次文档纠纷说起：交易系统里区块链到底在存什么
二手文档交易最麻烦的不是定价，而是"你怎么证明这文档是你的"。平台数据库被改一行记录，卖家就说不清了。这套基于区块链的文档交易系统，把文档注册、版权归属、售卖记录放进链上存证层——即使后面 MySQL 表被清空，合约事件和交易记录还在。项目核心是 Spring Boot 业务端 + Solidity 合约 + Web3j 节点对接，源码压缩包里附带完整部署文档和项目资料，运行时由真实验证，工程拆分清楚，适合软件工程、区块链方向的毕业设计，也适合想搞懂"智能合约怎么跟业务系统配合"的开发者。这条链路跑通后，你会发现区块链在这里不是噱头，而是卖家和买家都需要的证据链。
2. 智能合约与文档交易系统的核心架构设计
2.1 双层结构：链上存证，链下存文件
文档正文直接上链是不现实的：一篇几 MB 的 docx 转成 calldata 要把 gas 烧光，而且文档本身要能修改、能被下载，链上存它是反模式。这套系统的做法和大多数 DApp 一致——文件存本地资源目录或云存储，链上只留文档的 SHA-256 哈希、标题、价格、归属地址和状态。
业务上分成三层：浏览器前端负责上传和购买操作；Spring Boot 后端负责计算哈希、落盘文件、组装交易；区块链节点层负责接收交易并产生最终不可篡改的记录。后端在落库 MySQL 的同时，把关键字段同步提交到合约，MySQL 是查询视图，合约是真相来源。
这里有个值得说透的选型：为什么文档注册和交易要拆成两份逻辑，而不是塞进一个合约里写完。常见做法是拆分——存证合约管"登记、改状态、查归属"，交易侧持有存证合约地址，购买时先查存证合约的 status 再做转账。拆开的好处是存证逻辑独立，换交易撮合策略不动版权记录。合约语言选择 Solidity 而不是 Vyper 或 Rust，是因为部署文档和 Truffle 脚手架在 EVM 兼容链上的资料最全，换链成本也最低。
2.2 合约的数据结构：字段和存储
先看核心数据结构。合约里文档信息用结构体组织，字段含义如下表：
| 字段 | 类型 | 说明 |
|---|---|---|
| id | uint256 | 文档ID，从1自增 |
| owner | address | 上传者地址，即版权人 |
| title | string | 文档标题 |
| fileHash | bytes32 | 原文件SHA-256哈希，防篡改 |
| price | uint256 | 售价，单位wei |
| fileUrl | string | 文件的链下访问路径 |
| status | uint8 | 0未上架 1在售 2已售 3下架 |
| createdAt | uint256 | 注册时的区块时间戳 |
哈希用 bytes32 而不是 string，是因为 SHA-256 输出正好 32 字节，bytes32 占一个存储槽，比 string 省大量 gas。这也是很多初写合约的人容易忽略的细节——毕业设计里如果每个字段都用 string 存，部署和调用成本会明显偏高。
2.3 核心合约代码：注册、状态与购买
// SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract DocStore { struct Doc { uint256 id; address owner; string title; bytes32 fileHash; uint256 price; // 单位：wei string fileUrl; uint8 status; // 0未上架 1在售 2已售 3下架 uint256 createdAt; } mapping(uint256 => Doc) public docs; uint256 public docCount; event DocRegistered(uint256 indexed id, address indexed owner, bytes32 fileHash); event DocSold(uint256 indexed id, address indexed buyer, uint256 amount); function register(string calldata title_, bytes32 fileHash_, uint256 price_, string calldata fileUrl_) external returns (uint256) { docCount += 1; docs[docCount] = Doc(docCount, msg.sender, title_, fileHash_, price_, fileUrl_, 1, block.timestamp); emit DocRegistered(docCount, msg.sender, fileHash_); return docCount; } function buy(uint256 docId_) external payable { Doc storage d = docs[docId_]; require(d.status == 1, "not on sale"); require(msg.value >= d.price, "insufficient funds"); d.status = 2; emit DocSold(docId_, msg.sender, msg.value); } }register 里 msg.sender 就是调用地址，后端用哪个私钥签名，owner 就是哪个地址。fileHash_ 是后端传进来的 bytes32，合约不做二次哈希，只负责存证。buy 的前两行 require 分别拦住了"买已下架文档"和"付款不足"两种常见错误，require 条件不满足时交易会整体回滚，改不了半截状态。这里的精简版没有做资金分账和退款，完整源码里还会有托管账户和一个 withdraw 方法，逻辑上就是多一个 mapping 记录购买人，seller 可以调用取走余额。
你不需要在合约里写 if (msg.value > d.price) 的找零逻辑，链上交易天然支持差额返回，多付的 wei 会留在合约里，实际项目中通常由管理员统一结算。
3. Spring Boot 集成 Web3j：合约调用与文档上链实现
3.1 Web3j 接入层的构建
后端跟节点通信有三种常见方式：直接用 HTTP JSON-RPC 拼请求、用 Web3j SDK、或者用 Spring Boot 的 web3j 场景包。这套项目用的是 Web3j，理由很实际——合约用 Solidity 编译后生成的 Java 包装类可以直接 new 出合约对象，调用 register、buy 就像调本地方法，ABI 编解码、交易签名、nonce 管理都被封装掉了。直接拼 JSON-RPC 也不是不行，但代码里到处是十六进制字符串，调试成本翻倍。
pom 里引核心包：
<dependency> <groupId>org.web3j</groupId> <artifactId>core</artifactId> </dependency>版本号按项目源码里的 POM 锁定，部署文档里写的是用 Spring Boot 2.x 配套的 Web3j 4.x 系。接入 Bean 配置如下：
@Configuration public class Web3jConfig { @Value("${blockchain.rpc-url}") private String rpcUrl; @Value("${blockchain.owner-private-key}") private String privateKey; @Value("${blockchain.contract-address}") private String contractAddress; @Bean public Web3j web3j() { return Web3j.build(new HttpService(rpcUrl)); } @Bean public DocStore docStore(Web3j web3j) { Credentials credentials = Credentials.create(privateKey); return DocStore.load(contractAddress, web3j, credentials, new DefaultGasProvider()); } }这里三个配置项的分工要讲清楚。rpc-url 决定 Web3j 连哪个节点，部署文档里默认是 http://127.0.0.1:8545，也就是本机起的私有链或者 Ganache 开发链；contract-address 是合约部署完回显的地址，很多没跑通的案例都是因为合约重新部署后忘了同步这个配置；owner-private-key 是签名凭据，所有交易都由后端签名发出，这属于"后端钱包模式"，部署文档里强调私钥只放服务端环境变量，不要写进前端。
3.2 文档上链：从文件到交易回执
上链不是一个方法搞定的事，它是一条完整链路：文件落地 → 算哈希 → 调合约 → 等回执 → 解析日志。
public DocumentVO publish(MultipartFile file, String title, BigDecimal price) throws IOException { // 1. 文件落盘，返回可访问的相对路径 String fileUrl = storageService.save(file); // 2. 计算SHA-256，转成32字节哈希 String hashHex = DigestUtils.sha256Hex(file.getInputStream()); byte[] hashBytes = Numeric.hexStringToByteArray(hashHex); // 3. ETH转wei：避免double精度问题 BigInteger priceWei = price.multiply(BigDecimal.valueOf(1_000_000_000_000_000_000L)) .toBigIntegerExact(); // 4. 调用合约注册，返回交易回执 TransactionReceipt receipt; try { receipt = docStore.register(title, hashBytes, priceWei, fileUrl).send(); } catch (Exception e) { throw new BizException("上链失败，请检查节点连接或Gas设置", e); } // 5. 从事件日志中取回docId List<DocRegisteredEventResponse> events = docStore.getDocRegisteredEvents(receipt); if (events.isEmpty()) { throw new BizException("注册回执中没有事件日志", null); } return DocumentVO.of(events.get(0).docId, hashHex, fileUrl); }第 2 步用 DigestUtils.sha256Hex 对文件流计算，而不是对文件名计算——项目文档里也反复强调，任何一个字节变化哈希都会变，拿文件名做哈希等于没哈希。第 3 步的 price 用 BigDecimal 乘 10^18 再转 BigInteger，是在避免数据库 decimal 或 JSON 数字转 double 带来的精度丢失，链上金额一律用 wei 整数。第 5 步必须从回执日志里拿 docId，不能自己再 count+1，链上并发交易时本地计数不一定和实际写进链的顺序一致。
3.3 交易接口与授权下载的状态闭环
后端接口和合约方法对应关系如下：
| HTTP 接口 | 合约动作 | 业务含义 |
|---|---|---|
| POST /api/docs | register | 上传文档，落盘并上链存证，status置1 |
| GET /api/docs | 查 docs() / docCount() | 分页读MySQL再过滤链上状态 |
| POST /api/docs/{id}/buy | buy() | 买家发起购买，后端签名代付 |
| GET /api/docs/{id}/download | 查 status 与授权 | 校验链上已售且为当前买家 |
购买和下载之间有一个容易踩的坑：buy 里把 status 置为 2 后，后端如果还允许卖家自己下载，就失去了交易的意义。部署文档里的处理方式是下载接口先查 MySQL 订单表，再调链上 docs() 确认 status 和 buyer，两层校验都过才签发一次性下载 token。TOKEN 有效期设为 5 分钟，放在 Redis 里做防重放。接口层要做幂等，同一个订单重复点击购买时，后端应先查链上 status，status 已经是 2 就直接返回已售，而不是再发一笔转账交易，否则会多扣一次钱。
状态流转在链上只有 1→2 一步，下架和退款属于后台管理操作，由管理员私钥调单独的方法。这样设计的好处是交易主流程被压到最短，出问题的可能性最小。
4. 部署文档里的关键配置与节点联调排错
4.1 开发链与合约部署
这套项目的部署文档我按"先链后业务"的顺序看。先启动开发链，再编译部署合约，最后才启动 Spring Boot，顺序反了会出现合约地址还没写入配置，后端起来却连接空地址的尴尬。
# 安装依赖并启动Ganache开发链 npx ganache-cli --port 8545 --chain.chainId 1337 --gasLimit 8000000 # 另开终端，编译并部署合约 truffle compile truffle migrate --network development --reset--port 8545 是节点监听端口，rpc-url 要对应；--chain.chainId 1337 是链ID，签名交易里会带上它，节点发现链ID不匹配会直接拒绝交易；--gasLimit 8000000 给部署和合约调用留足空间，gasLimit 设太小，稍微复杂一点的 buy 调用就会报 out of gas。--reset 是强制重新部署所有合约，开发阶段几乎每次改合约都要带这个参数。
truffle migrate 跑完后终端输出里会有 contract address，这行输出要记下来，填进后端配置。项目资料里的部署文档在每一步都写了回车后的预期输出，照着核对就行。如果你的环境里没有 truffle-config.js 里的 development 网络，可以改成直接用一个 node 脚本加载编译产物、用 Web3 实例签名部署，效果一样，只是少了 migrations 的版本管理。项目源码里两种方式的脚本都有，优先用部署文档里带的那套。
4.2 后端配置与参数调优
blockchain: rpc-url: http://127.0.0.1:8545 chain-id: 1337 contract-address: '0x7ce7f4b7b1c63e062f2d9c0c24d1f4b0e3da6d9a' # 示例值，以migrate输出为准 owner-private-key: '0x4f3edf983ac636a65a842ce7c78d9aa706d3b113bce9c46f30d7d21715b23' gas-limit: 3000000 spring: datasource: url: jdbc:mysql://localhost:3306/doc_trade?useSSL=false&characterEncoding=utf8各配置项的坑：
| 配置项 | 推荐值 | 踩坑说明 |
|---|---|---|
| rpc-url | http://127.0.0.1:8545 | 不能用 https，Ganache 默认走 http |
| chain-id | 与节点一致 | 不一致报 ChainIdMismatchException |
| gas-limit | 3000000 以上 | 低于合约方法实际消耗会 out of gas |
| owner-private-key | 服务端环境变量 | 写进前端等于公开账户权限 |
这里 gas-limit 是后端发交易时给的 gasLimit，跟节点 --gasLimit 不是一个东西。节点那个是区块上限，后端这个是单笔交易上限。业务高峰期如果大量交易排队，建议把 rpc-url 换成负载均衡后的节点地址，而不是让所有人连同一个开发节点。
4.3 联调期最常见的三个报错
第一个是 InvalidAddressException 或 Bad response：合约地址写错或节点没同步完。排查时先 curl 节点的 eth_blockNumber，确认节点高度在动；再确认合约地址前缀 0x 和后端配置完全一致。
第二个是 ChainIdMismatchException：Ganache 的 chainId 和配置里不一致。解决方法是配置以节点启动参数为准，把 truffle-config.js 和 application.yml 两处 chainId 改成同一个值。
第三个是 out of gas：buy 调用失败率最高。原因是 buy 是 payable 且有 require 分支，真实消耗比 register 高，gas-limit 给到 8000000 更稳妥。注意不要为了省 gas 把 send() 改成异步后不拿回执，Web3j 的异步 API 在开发链上容易丢事件，联调阶段用同步 send() 最简单。
5. 用测试文档把交易闭环跑通的验证清单
5.1 先对哈希：文档存证的第一道检验
部署跑通后，找一个真实 Word 文档做测试，不要用空文件。
sha256sum 基于区块链的文档交易系统_测试文档.docx得到 64 位十六进制哈希，登录系统上传这份文档，再到链上查事件。Ganache 终端或 truffle console 都能看：
truffle console --network development DocStore.deployed().then(c => c.getPastEvents('DocRegistered', { fromBlock: 0, toBlock: 'latest' })).then(events => console.log(events[0].returnValues))核对事件里的 fileHash 与 sha256sum 输出完全一致。这个验证通过，说明"上传的文件没被改过"这个核心承诺成立。
5.2 购买与下载的闭环验证
用第二个账户执行购买，然后做三件事：查链上 Doc 的 status 是否变为 2；查 MySQL 订单表是否多了一条记录，金额精确到 wei；点击下载时，拿到的一次性 token 在 5 分钟后是否失效。第三个检查最容易漏——很多文档交易项目链上状态正确，但 token 不过期，等于把购买校验做成了摆设。
三个都通过，再重启 MySQL 并删除该文档的订单记录模拟"业务库丢失"，这时下载接口应该仍能通过链上记录放行。这一步是整个项目最有说服力的答辩演示，比讲一百句"区块链不可篡改"都有效。
5.3 给真实项目的三个补强点
部署文档之外，我会建议在这个基础上再做三处小改造。一是文档哈希从 SHA-256 升级到 Keccak-256，因为 Solidity 生态对 Keccak 原生支持，可以直接用 keccak256(abi.encodePacked(...)) 在合约里校验，省掉一次 Java 侧转换。二是把 fileUrl 指向 IPFS 而非本地磁盘，本地存储在高并发下载时带宽吃紧，IPFS 返回的 CID 天然可校验。三是给 buy 增加退款分支，让超付金额退回买家，订单取消时卖家退回文档状态，这几个方法在完整源码的项目资料里都有模板，照抄再改事件名即可。
本文还有配套的精品资源，点击获取
