跳到主要内容

官网系统后端开发指南

官网系统后端为 yudao-module-website 模块，集成在 yudao-server 中统一部署。

模块依赖​

<dependencies>
    <!-- Web 框架 -->
    <dependency>yudao-spring-boot-starter-web</dependency>
    <!-- 安全框架 -->
    <dependency>yudao-spring-boot-starter-security</dependency>
    <!-- MyBatis 持久层 -->
    <dependency>yudao-spring-boot-starter-mybatis</dependency>
    <!-- Excel 导入导出 -->
    <dependency>yudao-spring-boot-starter-excel</dependency>
    <!-- Redis 缓存 -->
    <dependency>yudao-spring-boot-starter-redis</dependency>
    <!-- 定时任务 -->
    <dependency>yudao-spring-boot-starter-job</dependency>
    <!-- 授权模块（validation） -->
    <dependency>yudao-module-validation</dependency>
    <!-- 系统模块（OAuth2/权限） -->
    <dependency>yudao-module-system</dependency>
    <!-- 会员模块（社交登录） -->
    <dependency>yudao-module-member</dependency>
    <!-- 基础设施（文件存储 FileApi） -->
    <dependency>yudao-module-infra</dependency>
</dependencies>

模块架构​

controller/
├── admin/                              # 后台管理接口 (/admin-api/website/)
│   ├── about/AboutController.java        # 公司信息、联系方式、团队
│   ├── analytics/AnalyticsController.java # 数据看板
│   ├── category/IndustryCategoryController.java # 行业分类
│   ├── config/SiteConfigController.java   # 站点配置
│   ├── contact/ContactMessageController.java # 联系留言
│   ├── demo/DemoEnvironmentController.java # 演示环境
│   ├── downloadlog/DownloadLogController.java # 下载日志
│   ├── policy/PolicyController.java       # 政策文档
│   ├── product/ProductReviewController.java # 产品评价
│   ├── solution/SolutionProductController.java # 解决方案/产品
│   └── source/SourcePackageController.java # 源码包
│
├── app/                                # 前台公开接口 (/app-api/website/)
│   ├── about/AppAboutController.java    # 关于我们
│   ├── analytics/AppAnalyticsController.java # 数据采集
│   ├── auth/AppWebsiteAuthController.java # 微信认证
│   ├── config/AppSiteConfigController.java # 站点配置
│   ├── contact/AppContactMessageController.java # 留言提交
│   ├── demo/AppDemoController.java      # 演示环境
│   ├── home/AppHomeController.java      # 首页聚合
│   ├── license/AppLicenseQueryController.java # 授权查询
│   ├── policy/AppPolicyController.java  # 政策文档
│   ├── product/AppProductController.java # 产品中心
│   ├── solution/AppSolutionController.java # 解决方案
│   ├── source/AppSourceDownloadController.java # 源码下载
│   └── user/AppUserCenterController.java # 用户中心

service/
├── about/AboutService.java              # 关于我们
├── analytics/                           # 数据采集与分析
│   ├── AnalyticsCollectService.java     # 采集接收
│   ├── AnalyticsPersistService.java     # 持久化
│   └── AnalyticsQueryService.java       # 查询
├── auth/WebsiteAuthService.java         # 微信认证
├── category/IndustryCategoryService.java # 行业分类
├── config/SiteConfigService.java        # 站点配置
├── contact/ContactMessageService.java   # 联系留言
├── demo/DemoEnvironmentService.java     # 演示环境
├── policy/PolicyService.java            # 政策文档
├── product/ProductReviewService.java    # 产品评价
├── solution/SolutionProductService.java # 解决方案/产品
└── source/SourcePackageService.java     # 源码包

dal/
├── dataobject/                          # 数据实体 (DO)
│   ├── about/AboutCompanyDO.java
│   ├── about/AboutContactDO.java
│   ├── about/TeamMemberDO.java
│   ├── analytics/DailyStatsDO.java
│   ├── analytics/EventLogDO.java
│   ├── analytics/FunnelStatsDO.java
│   ├── analytics/PageViewDO.java
│   ├── analytics/VisitPathDO.java
│   ├── category/IndustryCategoryDO.java
│   ├── config/SiteConfigDO.java
│   ├── contact/ContactMessageDO.java
│   ├── demo/DemoEnvironmentDO.java
│   ├── policy/PolicyDO.java
│   ├── product/ProductReviewDO.java
│   ├── solution/SolutionProductDO.java
│   ├── source/SourcePackageDO.java
│   └── source/DownloadLogDO.java
└── mysql/                               # MyBatis Mapper

job/
├── AnalyticsDailyAggregateJob.java      # 日度聚合任务
└── AnalyticsFlushJob.java               # 缓冲区刷新任务

util/
└── JsonFieldUtils.java                  # JSON 字段工具类

核心业务流程​

1. 微信认证流程​

复用 yudao-module-member 的社交登录链路：

1. 前台请求 /app-api/website/auth/qrcode → 生成微信授权 URL（含 sessionId）
2. 用户扫码 → 微信回调 /app-api/website/auth/callback
3. 回调中调用 member 模块的社交登录 → 注册/登录 → 生成双 Token
4. 前台轮询 /app-api/website/auth/check?sessionId={id} → 获取 Token
5. Token 刷新复用 member 模块的 /member/auth/refresh-token

2. 源码包下载流程​

1. 前台请求 /app-api/website/source/{id} → 获取源码包详情
2. 前台请求 /app-api/website/source/{id}/download → 下载鉴权
3. 后端检查用户授权状态 → 调用 validation 模块鉴权
4. 鉴权通过 → 调用 infra 模块 FileApi.presignGetUrl() → 生成预签名 URL
5. 记录下载日志 → 返回预签名 URL（有效期 5 分钟）

3. 首页数据聚合​

前台请求 GET /app-api/website/home/data
→ 聚合查询多个数据源：
  1. 站点配置 → Hero 区域、Banners、CTA
  2. 行业分类 → 分类树
  3. 解决方案产品 → 推荐方案/产品列表
  4. 关于我们 → 公司信息（统计数据、合作伙伴）
  5. 返回统一 AppHomeDataRespVO

错误码​

官网模块使用错误码段 1-009-000-000：

错误码说明
1_009_001_000行业分类不存在
1_009_001_001存在子分类，无法删除
1_009_001_002解决方案产品不存在
1_009_001_100源码包不存在
1_009_001_101源码包未发布
1_009_001_102源码包关联产品不存在
1_009_002_000演示环境不存在
1_009_003_000站点配置不存在
1_009_003_001站点配置键已存在
1_009_004_000团队成员不存在
1_009_005_000产品评价不存在
1_009_006_000政策文档不存在
1_009_007_000联系留言不存在

关键工具类​

JsonFieldUtils​

用于将 JSON 字符串安全解析为 Object，避免前端收到字符串 JSON：

public class JsonFieldUtils {
    public static Object parseJson(String jsonStr) {
        if (StringUtils.isBlank(jsonStr)) return null;
        try {
            return JsonUtils.parseObject(jsonStr, Object.class);
        } catch (Exception e) {
            return jsonStr; // 解析失败返回原字符串
        }
    }
}

适用于 gallery、features、stats、pricingPlans、techStack、changelog、envRequirements 等 JSON 字段。