简介一份基于 Java 的轻量级单商户商城系统源码适合中小商家、个人开发者及 Java 电商学习者参考用于快速搭建可对接小程序端的完整销售平台。项目以 Spring Boot 作为核心框架整合 MyBatis、Thymeleaf、Redis、Maven 等主流技术覆盖商品、订单、用户、支付等核心电商模块同时体现微服务拆分、小程序接口设计、数据库表结构规划、安全认证、Docker 部署和 CI/CD 流程并涉及日志监控、自动化测试、Git 版本管理等工程化实践能够帮助读者建立从开发到上线的完整认知。压缩包约 13.2MB文件总数与类型明细暂未列出但源码目录结构应能直接对应后端分层与各业务模块。当前已有 166 人浏览学习适合希望从零理解商城系统架构、接口写法与部署流程的开发者从中可获取项目分层设计、核心业务逻辑、小程序对接方式以及常见电商功能的可落地实现。1. 一套开源的 Java 商城小程序值不值得拿来当项目底座如果你是第一次见到 microapp-linjiashop 这个名字先别急着把它当成又一个“克隆项目”。它本质上是把一个多商户商城的后台管理系统、小程序前端、移动 H5 端和 Java 后端服务打包在一起的开源方案仓库主分支上通常写着 master所以你在 GitHub 上搜 linjiashop 时看到的源码包名往往带着 master 后缀。对想快速把商城小程序跑起来、或者拿 Java 项目练手的人来说它最大的价值是“省掉从零搭脚手架的时间”Spring Boot 做后端、MyBatis 访问 MySQL、Redis 做缓存小程序端直接对接业务接口。这一套结构很适合作为二次开发的地基但也正因为它是完整业务系统第一次上手时容易在数据库初始化、缓存依赖和微信端配置上卡住。这篇文章我就按自己落地这类项目时的习惯把它从导入到跑通、再到改造成多商户的路径讲清楚。2. 从 JDK 到前端工程先把 linjiashop 后端拆清楚再动手2.1 Java 后端的模块划分controller、service、mapper 在哪一层负责什么linjiashop 这类商城脚手架后端不管怎么分包本质都是三层结构。Controller 层负责接收小程序或 H5 发来的 HTTP 请求做参数校验后转发给 ServiceService 层写业务逻辑比如下单时要扣库存、生成订单号、记录流水Mapper 层通过 MyBatis 把对象映射成 SQL操作 MySQL 里的表。你打开源码时不要先看 controller而是先找 resources 目录下面的 mapper XML 文件因为商城这类业务里最常改的是 SQL不是 Java 代码。拿到代码第一件事是确认编译环境。常见做法是直接导入 IDE先看 pom.xml 里声明的依赖版本。如果你本机装的 JDK 太高比如直接用 JDK 17 去跑一个基于 JDK 8 写的项目编译时大概率会报“程序包不存在”或者“无法解析符号”这类玄学错误。我一般的做法是先把 pom.xml 里 spring boot 的 parent 版本记下来再对照本机 JDK 版本优先选 1.8 或 11 跑老项目。这里不是要你纠结版本号而是先确认项目在哪个 JDK 下能编译过再谈配置数据源。启动后端的顺序通常是这样先改 application.yml 或 application-dev.yml 里的数据库连接、Redis 地址、文件存储配置再启动 Redis最后运行 Spring Boot 主类。如果你懒得开 IDE直接用命令行也能跑在项目根目录执行 mvn spring-boot:run它会先编译再启动看到“Started Application in x seconds”就说明后端起来了。但很多第一次跑的人会在这里翻车最常见的坑是数据库连不上原因往往是本机 MySQL 的 root 密码和 yml 里写的不一致。2.2 代码根目录怎么看admin、api、wx 这些模块对应哪一端拿到 linjiashop 源码后先别急着问别人“哪个目录是小程序后端”你把根目录看成三个区域就清楚了。一个区域是后台管理端里面放商品管理、订单管理、用户管理的页面和接口给自己运营用另一个区域是对外 API给小程序和 H5 调用登录、商品列表、购物车、下单都走这里最后一个区域是数据库脚本和公共模块比如工具类、实体类、通用返回结果封装。有些版本还会拆出一个独立的前端工程目录里面放 uniapp 或原生微信小程序代码。我习惯在导入工程后先搜一个关键词“swagger”或“knife4j”因为大部分这类商城项目都会集成接口文档。启动后端后访问 swagger 页面你能直接看到所有外卖接口的参数和返回示例这是比读源码快得多的切入点。先确认接口文档能打开再拿文档里的字段去前端代码里对这样能少走很多弯路。微信小程序这一端代码目录结构一般分 pages、utils、components 三块。pages 里按业务分页面比如 index 首页、goods 商品详情、cart 购物车、order 订单列表utils 里放 request 封装和公共方法components 放自定义组件比如商品卡片、价格标签。前端联调时最重要的是 utils 里那个 request 文件因为整个小程序的接口前缀都集中在里面你只需要改一个 baseURL。很多新手喜欢在每个页面里写 wx.request结果后端接口域名一换就要全项目搜索替换这就是没吃透公共封装的结果。2.3 三个热点配置数据源、Redis、文件存储先改对跑通这套项目前有三个配置文件是必须动的。第一个是数据源通常在 application.yml 或 application-dev.yml 里你要把自己的数据库地址、账号、密码填进去库名要和 sql 初始化脚本创建的库一致。第二个是 Redis商城项目的商品缓存、验证码、会话状态都依赖它不启动 Redis 即使你数据库配置全对登录接口也会报错。第三个是文件存储商品图片和用户头像上传用的本地上传路径或云存储 key如果配错后台管理端一传图片就报 403 或路径不存在。改动这些配置时注意环境变量覆盖规则。常见做法是开发环境用 yml 里的默认值部署时通过启动参数覆盖比如 java -jar app.jar --spring.profiles.activeprod这样你不用把生产环境密码写进源码。这类商城源码里通常有多个环境的 yml 文件你先看默认激活的是哪个 profile再决定改哪个文件。很多人把配置改在了 application-prod.yml 里但启动时用的还是 dev结果半天不起作用这种问题排查起来最浪费时间。3. 本地跑通全套从 database 脚本到 controller 请求的最小命令3.1 初始化数据库找脚本、建库、导入一条链大多数 linjiashop 版本会附带 SQL 脚本一般在项目根目录的 sql 或 db 文件夹下。先找名为 linjiashop.sql 或 schema.sql 的文件如果找不到就在源码里搜“create table”。商城项目的表一般有几十张涵盖用户表、商品表、分类表、订单表、购物车表、支付记录表还有后台管理端用的管理员表和角色表。你不需要看懂每一张表但建库导入是第一步命令如下mysql -uroot -p -e CREATE DATABASE linjiashop DEFAULT CHARACTER SET utf8mb4 mysql -uroot -p linjiashop linjiashop.sql这里注意字符集一定要用 utf8mb4商城商品名称和用户备注里如果出现 emoji用 utf8 会报“Incorrect string value”错误这是老项目最常见的编码坑。导入完成后接下来去改后端配置文件里的连接信息。server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/linjiashop?useUnicodetruecharacterEncodingutf8mb4serverTimezoneAsia/Shanghai username: root password: 你的密码 redis: host: localhost port: 6379这段配置里最容易被忽略的是 url 后那一长串参数。一台机器上装了多个版本的 MySQL 时旧版本默认时区是系统时区新版本要求显式声明 serverTimezone否则启动时直接报“The server time zone value is unrecognized”。你要是看到这个报错不用去查什么深奥原因在 url 末尾加上 serverTimezoneAsia/Shanghai 就行。3.2 启动后端jar 还是 IDE参数怎么传导入数据库后启动后端有两条路。一条是在 IDE 里直接运行启动类的 main 方法适合开发调试另一条是打 jar 包用命令行跑适合测试环境验证。先说 IDE 跑法打开启动类右键运行等控制台里出现“Started Application in”字样说明启动成功。如果启动失败先看日志里是哪个 bean 初始化报错数据库连接失败和 Redis 连接失败报错信息完全不一样不要稀里糊涂地反复重试。再说 jar 包打法和启动。在项目根目录执行 mvn clean package -Dmaven.test.skiptrue等 target 目录下生成 jar 文件然后用 java -jar 启动mvn clean package -Dmaven.test.skiptrue java -jar target/linjiashop-admin.jar --spring.profiles.activedev这里要解释下为什么要跳过测试商城项目里的测试类经常依赖测试数据库没有配置测试环境数据源时mvn package 会卡在 test 阶段报错。跳过测试不是不负责任而是你本地第一次跑通时先排除干扰因素。启动后验证方式很简单浏览器访问 http://localhost:8080如果看到登录页或者接口返回 JSON说明后端已就绪。项目启动阶段有个冷知识值得留意Spring Boot 2.x 之后默认不解析 jsp很多老商城前台模板是 thymeleaf 或 freemarker。如果你发现浏览器访问首页报 404 或 Whitelabel Error Page别改端口先确认模板引擎依赖是否包含在 pom.xml 里。3.3 小程序端联调微信开发者工具导入与 requestUrl后端跑通后接着处理小程序前端。打开微信开发者工具选择“导入项目”把 linjiashop 前端目录选中填上自己的 AppID没有就选测试号。首次导入最常遇到的问题是小程序基础库版本过低导致某些 API 不兼容解决方法是把本地设置里的调试基础库调高一点。前端工程里的关键改动是请求地址。打开 utils 下的 request.js 或 config.js找到 BASE_URL 或 baseUrl 变量改成你本机的局域网 IP比如 http://192.168.1.100:8080。注意这里有两个细节第一微信开发者工具里勾选“不校验合法域名”才能访问非 https 地址第二不要填 localhost因为手机预览时 localhost 指的是手机自己要填电脑的局域网 IP。这两条是联调阶段 90% 连不上后端的根因。const BASE_URL http://192.168.1.100:8080 export const request (url, method, data) { return new Promise((resolve, reject) { wx.request({ url: BASE_URL url, method: method, data: data, success: (res) { if (res.data.code 0) { resolve(res.data.data) } else { reject(res.data.msg) } }, fail: reject }) }) }上面这段代码里常见的约定是 code 为 0 时接口返回正常非 0 时返回业务错误码。每个商城项目定义的 code 含义不同你联调前先打开一个页面看 console 里的网络请求确认后端返回的 JSON 结构到底是什么再决定怎么封装。很多人直接把后端接口数据打印出来发现字段对不上就怀疑代码坏了其实是前端封装里把 code 判断写死了。4. 商城小程序联调最容易翻车的四个地方4.1 数据库时区问题导致订单时间错乱现象后台管理端看到的订单创建时间比实际时间慢了 8 小时或者小程序端下单后列表里显示“刚刚”但详情页时间不对。原因MySQL 连接串没显式指定时区而 mysql-connector-java 8.x 默认按服务器时区解析日期。如果数据库服务器时区是 UTCJava 侧按本地时区处理就会出现 8 小时偏移。解决在数据源 URL 里加上 serverTimezoneAsia/Shanghai同时确认 MySQL 系统时区。执行 SQL 看当前时间SELECT NOW()。如果你发现数据库时间本身就不对在 MySQL 配置文件里加 default-time-zone 08:00 后重启服务。这类问题不涉及业务代码属于环境参数玄学排查顺序永远先看配置再看代码。另一个隐藏坑是 JSON 序列化的日期格式。商城项目里订单时间通常会返回给前端如果后端返回的是时间戳前端直接 new Date(timestamp).format 即可如果返回的是 ISO 字符串小程序端 iOS 和 Android 的解析行为有差异。我的习惯是前后端约定返回时间戳从源头避免端上兼容问题。4.2 商品图片加载不出来但接口有数据现象商品列表能打开文字都对但图片区域全是灰块或裂图。有些人会怀疑是后端返回的图片字段名不对但打印数据看字段是有的。原因商品表里存的是相对路径比如 /upload/20240101/a.jpg而后端配置的文件访问前缀写的是 localhost。你在电脑上模拟器里看得见手机真机预览时 localhost 指向手机自己自然加载不到电脑上的图片。解决把文件访问前缀改成局域网 IP 或完整公网地址。找到后端配置里文件上传的基础路径一般是类似 file.local.url 或 storage.domain 的配置项。如果是nginx 做过磁盘映射还需要确认目录权限。这个坑最让人头疼的地方是“电脑上正常、手机上挂”因为问题根本不在代码里而是访问地址的可见性不同。遇到图片问题先看两个地方数据库里存的路径、后端实际输出图片的 URL两者拼接起来在浏览器里打开看看有没有响应。另外如果图片是用户上传的头像还需要检查上传接口是否启用了 OSS。很多开源商城默认对接了阿里云 OSS 或 AWS S3你没填密钥时它会走本地存储但本地存储的目录没创建上传时直接报文件不存在。第一次跑的时候不要高估源码健壮性本地存储目录不存在很常见。4.3 登录状态时灵时不灵接口偶尔报未登录现象小程序里刚登录完切到另一个页面再操作提示“token 失效”或“未登录”。有时候清理缓存重新登录就好了但过一会儿又犯。原因token 过期时间设置太短或者 Redis 里的 session 被清掉了。商城项目的登录态一般是后端生成 token 存 Redis前端每次请求在 header 里带 token。如果你把 Redis 的过期时间配成 30 分钟用户停在商品详情页看了一会后再加购就会触发“未登录”。解决先看后端 token 有效期配置一般写在 yml 里如 token.expireTime。调试阶段直接改成 7 天跑通后再按业务需要收紧。同时检查 Redis 使用的 key 前缀如果不同环境共用同一套 Rediskey 可能互相覆盖。另外有个容易被忽略的细节小程序端 request 封装里是否在登录后把 token 存到了 storage并且每次请求都取出来放 header。有的前端代码只在登录页写了 token 写入但请求封装里没有读 header导致 token “有名无实”。4.4 微信支付回调地址配置错导致支付成功后订单没更新现象支付能发起微信也扣款了但小程序端订单状态一直是“待支付”后台也没有支付流水。原因微信支付要求配异步回调 URL商城项目一般把回调地址写在 yml 或数据库配置里。本地联调时你配的是 http://localhost:8080/pay/callback微信服务器在公网访问不到你的 localhost回调自然失败。又因为支付成功了这单就卡在中间态。解决本地开发推荐用内网穿透工具把本机端口暴露到公网然后把回调地址改成穿透后的域名。如果你只是想验证下单链路先用测试模式模拟支付成功把回调地址临时改成前端跳转跑通后再接真实微信支付。支付联调这块涉及商户号、证书、回调验签每一步配置都能单独写一篇排错。这里的核心经验是支付成功不等于订单更新成功你必须同时确认微信侧回调日志和后端接口日志。5. 想把 linjiashop 改成自己的多商户商城先过三道坎5.1 单商户表结构怎么加 tenant_id默认的商城源码多数是单商户模型。商品表、订单表、购物车表里没有商家概念后台也是单人运营。想改成多商户常规做法是给核心业务表加 tenant_id 字段查询时强制带上当前商户 id。常见做法不是改关联查询而是在最底层加一个数据权限拦截否则你每写一个 SQL 都忘加 tenant_id数据就串了。实现上可以用 MyBatis 的拦截器在 SQL 执行前自动拼上 tenant_id 条件。这样已有代码改动最小但要注意拦截器对聚合查询、子查询的影响容易生成非法 SQL。我自己的经验是先看这个源码里是否原本有“店铺”表。如果有多商户改造成本就低没有的话就得先建 shop 表再把 user、goods、order 关联过去。字段加完还有一个更关键的地方后台管理端和商家端必须分别处理数据范围。商家登录后只看得到自己的商品和维护自己的订单这需要前端菜单权限和后端数据权限双重配合单单加字段还不够。5.2 商品库存和秒杀超卖底线在哪里商城源码里最值钱的逻辑其实是库存在并发下的表现。你要留意下单时是怎么扣库存的很多老项目直接用 update goods set stock stock - 1 where id ?在低并发下没问题但一上活动就超卖。常见修正方式是把扣库存改成乐观锁加条件判断update goods set stock stock - #{num} where id #{goodsId} and stock #{num}这条 SQL 通过 where 条件里对 stock 的判断来防止负数库存同时数据库行锁来保证单条 update 串行化。但如果你还要同时写订单、扣减多个商品、记录库存流水单条 SQL 就不够了还得引入事务和补偿。这里要认清现实这套商城源码的定位是教学和中小商家秒杀这种场景不是加个字段能解决的。如果你要跑高并发活动建议把秒杀单独拆出来用 Redis 预减库存加异步落库而不是在单体项目里硬扛。从运营角度看库存数据一致性比实时性重要。前台可以接受短暂显示有库存但下单失败的“拥挤”提示但不能接受减了库存但没生成订单。源码默认逻辑往往把扣库存和生成订单写在同一个事务方法里你改代码时务必保持这个边界不要为了优化性能把两步拆开。5.3 上线部署Linux 下 jar 包和 nginx 的配置套路跑通本地后上线部署时会有新的坎。多数人第一步就卡在服务器端口上项目用 8080nginx 用 80你得配置反向代理。后端不用暴露到公网只让 nginx 转发即可。nginx 配置里最容易出问题的是 /api 前缀的 location 匹配如果后端接口路径带 /api 而前端请求里也带转发时就别再重复加一层。一键部署的做法是把 jar 用 systemd 托管保证进程崩了能自动拉起。常见命令是建一个 service 文件写 ExecStart 指向 java -jar 全路径和启动参数。这一步最容易被忽略的是 JVM 内存参数商城的图片上传、报表导出都会吃内存如果服务器只有 2G 内存默认堆配置可能直接 OOM。我的习惯是显式设置 -Xms512m -Xmx512m宁可早死早重启也不让它把机器内存耗尽拖垮整个系统。nginx 配置里还有一个隐藏细节上传文件大小限制。后台上传商品图超过 2M 会报 413但你查后端日志一无所获其实是 nginx 的 client_max_body_size 默认只有 1m。把基础配置改成如下能解决大部分图片上传失败问题server { listen 80; server_name your-domain.com; client_max_body_size 50m; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }部署时的另一个常见问题是静态资源访问。前端图片通过后端 /upload 路径暴露但 nginx 里没有对应的 location 规则结果路由到 jar 上处理了。虽然也能访问但增加了后端压力。正确做法是让 nginx 直接代理上传目录location /upload/ { alias /data/linjiashop/upload/; }6. 拿到源码后怎么验证它真的是完整可落地的商城一条主链路和三个调试锚点6.1 先跑通“登录、看商品、加购、下单”这条核心链路启动完前后端别急着翻代码先手工走一遍核心链路。小程序端打开项目后正常能从首页看到商品列表点击商品进详情点“加入购物车”再去购物车结算最后提交订单。如果你能走完这条链路说明数据库、后端接口、前端页面三者的字段是通的。走不通时按顺序看微信开发者工具的 console 报错、后端控制台日志、数据库表结构。我见过很多人项目起不来就怀疑代码有问题其实大多数是 Redis 没启动或者 MySQL 密码不对。这条链路还帮你验证另一个重要问题小程序端有没有连对后端。如果你改了 request.js 里的地址还是走的旧接口大概率是改了代码后没重新编译或没刷新小程序。微信开发者工具导入项目后一定要先“编译”再“预览”即使代码保存了页面不刷新也用的是旧逻辑。6.2 三个必看的日志位置哪里出问题一眼定位跑通链路后真正要用的调试锚点是日志。第一处是后端控制台日志Spring Boot 默认打到控制台同时会写到 logs 目录。看到 ERROR 级日志时先看堆栈里的第一行经常能直接定位是数据库连接还是空指针。第二处是小程序端 consolerequest 请求返回后打印 res.data你才能看清接口真实返回结构。第三处是 MySQL 的慢查询日志如果商城首页打开很慢把 sql_mode 和索引检查一遍商品表的 category_id 外键和 goods_name 的模糊查询是两个常见瓶颈。我习惯在做完一次功能改动后同时打开这三处日志然后跑一次主链路。前端报错不一定在前端后端没报错也不代表逻辑对。比如下单成功但库存没减后端看不到异常但日志里必然少了扣库存那条 SQL 记录。有经验的工程师不会只盯着控制台而是把一条请求从前端到后端的完整路径走一遍前端发起请求、后端 controller 接收、service 执行、mybatis 输出 SQL、数据库返回结果。哪个环节缺了日志问题就藏在那里。6.3 把省下来的时间花在数据一致性与幂等改造上当你跑通项目、确认能上线、甚至已经部署到了测试服务器后接下来的优化重点不该是研究新功能而是补齐边界。商城系统最怕的不是功能少而是数据对不上。比如用户下单时点击多次提交按钮会不会生成两笔相同金额的订单微信支付回调因为网络抖动发来两次订单会不会被重复更新这类问题在单机开发时不一定出现但并发一上来必现。处理重复提交的常见做法是前端在提交按钮上加 loading 和禁用后端在创建订单接口里加防重令牌前端请求时先向后端要一个 token下单时带上 token后端校验 token 存在且未被使用后才允许创建订单。这个 token 可以存在 Redis 里设置五分钟过期。这种方式改造成本低却能挡住绝大多数重复单。更深一层是幂等改造也就是接口接收同一个请求多次产生的结果和接收一次相同。对订单来说支付回调接口必须做幂等处理方式是先查订单状态只有“待支付”状态才更新为“已支付”否则直接返回成功。不加这个判断用户支付一次钱后台可能看到两条支付流水。最后我还要强调一个习惯每次上线前把新增的表、字段、接口统一在文档里登记一次不要依赖记忆。你不是在维护一套玩具项目是在给别人和自己留后路。希望这篇笔记帮你在折腾 linjiashop 时少走几圈弯路。本文还有配套的精品资源点击获取