# java-standard-proj

**Repository Path**: kbzero/java-standard-proj

## Basic Information

- **Project Name**: java-standard-proj
- **Description**: 标准生产环境Java项目，包含实际生产过程中的全套Config 和 Best Practice
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-15
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Java Standard Backend Project

#### 项目介绍
标准生产级Java后端项目，基于Spring Boot 3.x构建，集成了企业级开发中常用的全套组件和最佳实践配置。

#### 技术栈

| 组件 | 版本 | 说明 |
|------|------|------|
| **Spring Boot** | 3.3.10 | 核心框架 |
| **JDK** | 17 | 运行环境 |
| **MySQL** | 8.0 | 数据库 |
| **Redis** | 7.x | 缓存与Session存储 |
| **Nacos** | 2.3.0 | 配置中心与服务发现 |
| **MyBatis Plus** | 3.5.7 | ORM框架增强 |
| **JWT** | 0.12.5 | 认证与授权 |
| **Spring Security** | 6.x | 安全框架 |
| **ELK Stack** | 8.11.1 | 日志收集与分析 |
| **Docker** | - | 容器化部署 |
| **Maven** | 3.9.6 | 构建工具 |

#### 环境要求

- **JDK 17+**
- **Maven 3.9+**
- **Docker 20.10+** (可选，用于容器化部署)
- **MySQL 8.0+**
- **Redis 7.0+**
- **Nacos 2.3.0+**

#### 快速开始

##### 1. 使用 Docker Compose 一键启动（推荐）
```bash
# 启动所有依赖服务（MySQL, Redis, Nacos, ELK）
docker-compose up -d mysql redis nacos elk

# 等待服务启动后，启动应用
docker-compose up -d app
```

应用启动后访问：
- 应用接口：http://localhost:9001/api
- Nacos控制台：http://localhost:8848/nacos (用户名/密码：nacos/nacos)
- Kibana仪表板：http://localhost:5601
- 健康检查：http://localhost:9001/api/actuator/health

##### 2. 本地开发启动
```bash
# 克隆项目
git clone [项目地址]
cd java-standard-proj

# 配置数据库（确保MySQL和Redis已启动）
# 修改 src/main/resources/application.yml 中的数据库连接配置

# 编译并运行
mvn clean package
java -jar target/*.jar
```

#### 项目目录结构
```
src/
├── main/
│   ├── java/org/example/
│   │   ├── config/          # 配置类（Security, Redis, MyBatis Plus等）
│   │   ├── controller/      # REST控制器
│   │   ├── entity/         # 实体类（包含DTO, Request, Response）
│   │   ├── mapper/         # MyBatis Mapper接口
│   │   ├── service/        # 业务服务层（接口与实现分离）
│   │   ├── filter/         # 过滤器（JWT认证等）
│   │   └── utils/          # 工具类
│   └── resources/
│       ├── mapper/         # MyBatis XML映射文件
│       ├── application.yml # 主配置文件
│       ├── logback-spring.xml # 日志配置（支持ELK）
│       └── schema.sql      # 数据库初始化脚本
└── test/                   # 单元测试
```

#### 配置说明

##### 数据库配置
项目使用MySQL数据库，配置位于 `application.yml`：
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/test_db
    username: root
    password: root.2026
```

##### Redis配置
```yaml
spring:
  redis:
    host: localhost
    port: 6379
    password: 
    database: 0
```

##### Nacos配置中心
```yaml
spring:
  cloud:
    nacos:
      config:
        server-addr: localhost:8848
        namespace: 
        group: DEFAULT_GROUP
```

##### JWT配置
```yaml
jwt:
  secret: your-secret-key-change-in-production
  expiration: 28800  # 8小时
```

##### 日志配置
- 使用Logback框架，支持ELK日志收集
- 日志文件自动按天分割，保留30天
- 支持JSON格式输出到Logstash

#### 代码规范

##### 1. 命名规范
- **包名**：全小写，采用公司域名反写（如 org.example）
- **类名**：大驼峰式（如 UserController）
- **方法名**：小驼峰式（如 getUserById）
- **变量名**：小驼峰式
- **常量名**：全大写，下划线分隔（如 MAX_COUNT）

##### 2. 分层架构
- **Controller层**：处理HTTP请求，参数校验
- **Service层**：业务逻辑实现，事务管理
- **Mapper层**：数据库操作
- **Entity层**：数据模型（包含DTO, VO, Request, Response）

##### 3. 提交规范（Conventional Commits）
项目使用约定式提交规范，提交信息格式：
```
<type>[scope]: <description>
```

**可用类型：**
- `feat`：新功能（feature）
- `fix`：修复bug
- `refactor`：重构代码（既不是新功能也不是修复）
- `test`：测试相关
- `docs`：文档更新
- `style`：代码格式调整
- `chore`：构建过程或辅助工具变动
- `perf`：性能优化
- `ci`：CI配置变更
- `build`：构建系统或外部依赖变更
- `revert`：回滚提交

**示例：**
```
feat: 添加用户登录功能
fix(auth): 修复登录token过期问题
refactor: 重构用户服务层
test: 添加用户注册单元测试
```

#### 安全特性
- **JWT认证**：基于Token的无状态认证
- **Spring Security**：RBAC权限控制
- **密码加密**：使用BCryptPasswordEncoder
- **SQL防注入**：MyBatis Plus参数化查询
- **CORS配置**：跨域资源共享

#### 监控与健康检查
- Spring Boot Actuator集成
- 健康检查端点：`/actuator/health`
- 指标收集：`/actuator/metrics`
- Prometheus监控支持

#### 部署方案

##### Docker部署
```bash
# 构建镜像
docker build -t java-standard-backend:latest .

# 运行容器
docker run -d -p 9001:9001 \
  -e MYSQL_HOST=mysql-host \
  -e REDIS_HOST=redis-host \
  -e NACOS_SERVER=nacos-host:8848 \
  java-standard-backend:latest
```

##### Kubernetes部署
参考 `k8s/` 目录下的部署文件（待补充）

#### 参与贡献

1. **Fork 本仓库**
2. **创建功能分支** (`git checkout -b feat/your-feature`)
3. **提交代码** (遵循约定式提交规范)
4. **推送分支** (`git push origin feat/your-feature`)
5. **新建 Pull Request**

#### 许可证

本项目基于 MIT 许可证开源，详见 [LICENSE](LICENSE) 文件。