Skip to content

docs: add comprehensive README files in English and Chinese #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
megadotnet merged 1 commit into from
May 28, 2026
Merged

docs: add comprehensive README files in English and Chinese #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 119 additions & 0 deletions README-ZhCn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
# AuthApp - Spring Boot 登录认证应用

[![English](https://img.shields.io/badge/Language-English-blue.svg)](README.md)
[![简体中文](https://img.shields.io/badge/Language-%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87-red.svg)](README-ZhCn.md)

## 项目介绍

AuthApp 是一个综合性的示例应用程序，展示了安全的 REST API 和前端集成。它提供标准的身份验证功能，包括登录、注销、带有电子邮件验证的用户注册、“记住我”功能、密码重置以及多语言支持。该应用程序使用 JWT (JSON Web Tokens) 和 Spring Security 进行安全保护。

## 技术栈清单

本项目采用了现代化的技术栈，分为前端、后端、基础设施和工具链四个核心部分。

### 1. 后端 (语言与运行环境)
* **Java 21 (Eclipse Temurin JDK 21 LTS):** 核心编程语言及运行环境。
* **Spring Boot (3.3.5):** 用于快速构建应用程序的基础框架。
* **Spring Security:** 提供身份验证和授权功能。
* **Spring Data JPA:** 简化数据访问层的实现。
* **Spring Boot Actuator:** 提供生产级别的监控和指标统计功能 (`/actuator/health`, `/actuator/metrics`)。
* **Undertow:** 默认的嵌入式 Web 服务器，用于替代 Tomcat。
* **jjwt (0.6.0):** 用于生成和验证 JSON Web Token，实现无状态身份验证。
* **springdoc-openapi (2.0.4):** 自动生成 OpenAPI 文档并提供 Swagger UI 界面 (`/swagger-ui.html`)。
* **Alibaba Druid (1.1.9):** 高性能数据库连接池，内置监控功能 (`/druid/index.html`)。
* **Lombok (1.18.34):** 消除 Java 代码中的样板代码（如 getters, setters 等），提高开发效率。
* **Joda-Time (2.9.9):** 用于高级日期和时间处理。
* **JavaMailSender:** 处理电子邮件发送，用于账户验证和密码重置。

### 2. 前端框架
* **AngularJS (1.5.8):** 核心前端 JavaScript 框架，用于构建单页面应用程序 (SPA)。
* **Bootstrap (3.3.7):** CSS 框架，用于响应式设计和 UI 组件。
* **jQuery (1.9.1 - 3.x):** Bootstrap JavaScript 插件所依赖的基础库。
* **Angular UI Router:** 管理 AngularJS 应用程序中的路由和状态。
* **angular-translate:** 提供国际化 (i18n) 和本地化支持。
* **Thymeleaf:** 主要用于提供初始视图或在需要时进行服务器端模板渲染。

### 3. 基础设施与数据库系统
* **H2 Database (内存数据库):** 默认用于本地开发和测试的数据库。可通过 `/h2-console` 访问控制台。
* **MySQL Connector/J (8.0.33):** 数据库驱动程序，用于连接生产环境的 MySQL 数据库。
* **Qiniu SDK (7.2.x):** 集成七牛云，用于云存储或 CDN 功能。
* **Docker:** 用于应用程序的容器化和部署。

### 4. 工具链与构建依赖
* **Maven (3.8+):** 项目管理和构建工具。
* **spotify/dockerfile-maven-plugin (1.3.6):** 在 Maven 构建生命周期中自动化构建 Docker 镜像。
* **SpotBugs Maven Plugin (4.8.2.0):** 静态代码分析工具，用于发现 Java 代码中潜在的 bug，并集成了 FindSecBugs 进行安全漏洞分析。

## 环境依赖要求

为避免环境冲突，请确保满足以下最低要求：
* **JDK:** 最低版本 21 (强烈建议使用 Eclipse Temurin JDK 21 LTS)。
* **Maven:** 最低版本 3.8.1 (注意：项目中未包含 Maven Wrapper `mvnw`，因此必须在系统环境变量中显式安装配置 Maven)。
* **Docker:** 仅当您计划以容器形式构建和运行应用程序时才需要。

## 本地部署与启动步骤

以下步骤适用于主流的 Windows、macOS 和 Linux 开发环境。

### 1. 克隆代码仓库
```bash
git clone <repository_url>
cd <repository_directory>
```

### 2. 编译打包项目
使用 Maven 构建应用程序。如果不需要在构建时执行测试，可以跳过测试。
```bash
mvn clean package -DskipTests
```

### 3. 运行应用程序
使用 Spring Boot Maven 插件运行应用程序。默认的应用端口配置为 `7081`。

**本地调试模式 (使用 H2 内存数据库):**
```bash
mvn spring-boot:run -Dspring-boot.run.profiles=local
```
*(或者，您可以直接运行构建好的 jar 包: `java -jar target/springboot-login-application-1.0.0.jar`)*

**生产环境模式:**
对于生产环境，需要先在配置文件中配置 MySQL 数据库的连接字符串。
```bash
mvn spring-boot:run -Dspring-boot.run.profiles=prod
```

### 4. Docker 部署 (可选)
构建 Docker 镜像：
```bash
mvn clean package dockerfile:build -DskipTests
```
运行 Docker 容器：
```bash
docker run -p 7081:7081 -e "SPRING_PROFILES_ACTIVE=local" -m='2g' --name springboot-login-app -d megadotnet/springboot-login-application
```

## 项目结构说明

```text
├── src
│ ├── main
│ │ ├── java/com/app/login # 后端 Java 源代码 (Controllers, Services, Repositories, Security 等)
│ │ └── resources # 配置文件 (application.yml, 国际化 properties 文件, 邮件模板)
│ │ └── static # 前端静态资源 (AngularJS 应用代码, HTML, CSS, JS, Bower 依赖)
│ └── test # 单元测试和集成测试代码
├── pom.xml # Maven 项目对象模型，管理项目依赖和构建插件
└── Dockerfile # Docker 配置文件，用于应用程序容器化
```

## 开发规范

* **代码风格:** 项目遵循标准的 Java 编码规范。项目大量使用了 Lombok；请确保您的 IDE 安装了 Lombok 插件并开启了注解处理 (Annotation Processing)。
* **REST API:** 所有 API 都应遵循 RESTful 原则进行设计，并使用 Swagger/OpenAPI 进行文档化。
* **安全规范:** 所有端点（除了登录/注册等公开接口外）必须受到安全保护。必须使用 Spring Boot Validation 验证所有用户输入。
* **测试规范:** 为所有核心业务逻辑编写单元测试。在提交代码之前，请运行 `mvn clean test` 确保所有测试均能顺利通过。

## 常见问题排查

1. **端口被占用 (Port Already in Use):** 如果应用程序因为 7081 端口被占用而无法启动，请停止冲突进程或在 `src/main/resources/application.yml` 中修改端口配置 (`server.port: 7081`)。
2. **Lombok 编译错误:** 如果您的 IDE 提示找不到 getters/setters 相关的 symbol，请检查 IDE 是否已安装 Lombok 插件，并确认在设置中勾选了 "Enable annotation processing"。
3. **数据库连接失败:** 当使用 `prod` 配置文件启动时，请确保您的 MySQL 实例正在运行，且配置文件中的用户名和密码等连接信息完全正确。
216 changes: 114 additions & 102 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,107 +1,119 @@
# Spring-Boot Demo [![Build Status](https://travis-ci.org/megadotnet/SpringBootDemoApp.png?branch=master)](https://travis-ci.org/megadotnet/SpringBootDemoApp/)
A Sample application developed with :
1. Spring Boot 2 REST API
2. Spring Security
3. Spring Data JPA
4. Spring Boot Actuator
5. Angular JS
6. Alibaba Druid
7. Lombok
8. joda-time
Application is secured with JWT and Spring security.


## Feature includes:
1) Standard login and logout
2) Registration and email verification
3) Remember me functionality
4) Forgot password
5) Multi-language support
6) RESTful API

## Spring Actuator
Spring Boot includes an Actuator module,which introduces production-ready non-functional requirements
to your application. The Spring Boot Actuator module provides monitoring, metrics, and auditing right out
of box.

/actuator/metrics
This endpoint shows the metrics information of the current application, where you can determine the how
much memory it’s using, how much memory is free, the uptime of your application, the size of the heap is
being used, the number of threads used, and so on.

/actuator/health
Displays your application’s health status.

## Swagger

Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

Link

http://127.0.0.1:7080/swagger-ui.html
## Druid
Druid is one of the best database connection pools written in JAVA. The Web console url goes to:
http://127.0.0.1:7080/druid/index.html

## H2 Web Console
By default the console can be accessed at URI ```http://127.0.0.1:7080/h2-console``` which can be changed by spring.h2.console.path property.
## Testing
JWT http request
``` POST http://127.0.0.1:7080/api/authenticate HTTP/1.1
User-Agent: Fiddler
Host: 127.0.0.1:7080
Content-Length: 65
content-type: application/json
{"username": "admin", "password": "admin", "rememberMe": "false"}
# AuthApp - Spring Boot Login Application

[![English](https://img.shields.io/badge/Language-English-blue.svg)](README.md)
[![简体中文](https://img.shields.io/badge/Language-%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87-red.svg)](README-ZhCn.md)

## Project Introduction

AuthApp is a comprehensive sample application demonstrating a secure REST API and frontend integration. It provides standard authentication features including login, logout, user registration with email verification, "remember me" functionality, password reset, and multi-language support. The application is secured using JWT (JSON Web Tokens) and Spring Security.

## Technology Stack

The project utilizes a modern technology stack separated into frontend, backend, infrastructure, and toolchain components.

### 1. Backend (Language & Runtime)
* **Java 21 (Eclipse Temurin JDK 21 LTS):** The core programming language and runtime environment.
* **Spring Boot (3.3.5):** The foundational framework for rapid application development.
* **Spring Security:** Provides authentication and authorization capabilities.
* **Spring Data JPA:** Simplifies data access layer implementation.
* **Spring Boot Actuator:** Offers production-ready features like monitoring and metrics (`/actuator/health`, `/actuator/metrics`).
* **Undertow:** The default embedded web server replacing Tomcat.
* **jjwt (0.6.0):** Used for JSON Web Token generation and validation for stateless authentication.
* **springdoc-openapi (2.0.4):** Generates OpenAPI documentation and provides Swagger UI (`/swagger-ui.html`).
* **Alibaba Druid (1.1.9):** High-performance database connection pool with built-in monitoring (`/druid/index.html`).
* **Lombok (1.18.34):** Reduces boilerplate code (getters, setters, etc.) during development.
* **Joda-Time (2.9.9):** Used for advanced date and time manipulation.
* **JavaMailSender:** Handles sending emails for account verification and password resets.

### 2. Frontend Framework
* **AngularJS (1.5.8):** The core frontend JavaScript framework for building the single-page application (SPA).
* **Bootstrap (3.3.7):** The CSS framework for responsive design and UI components.
* **jQuery (1.9.1 - 3.x):** Required dependency for Bootstrap JavaScript plugins.
* **Angular UI Router:** Manages routing and states within the AngularJS application.
* **angular-translate:** Provides internationalization (i18n) and localization support.
* **Thymeleaf:** Used minimally for serving the initial view or server-side templates if required.

### 3. Infrastructure & Database Systems
* **H2 Database (In-Memory):** The default database for local development and testing. The console is accessible at `/h2-console`.
* **MySQL Connector/J (8.0.33):** The database driver for connecting to a production MySQL database.
* **Qiniu SDK (7.2.x):** Integrated for cloud storage or CDN capabilities.
* **Docker:** Used for containerization and deployment.

### 4. Build Tools & Toolchain
* **Maven (3.8+):** The project management and comprehension tool used for building the application.
* **spotify/dockerfile-maven-plugin (1.3.6):** Automates the building of Docker images during the Maven build lifecycle.
* **SpotBugs Maven Plugin (4.8.2.0):** Static code analysis tool to find potential bugs in Java code, integrated with FindSecBugs for security analysis.

## Environment Requirements

To avoid environment conflicts, ensure the following minimum requirements are met:
* **JDK:** Version 21 (Eclipse Temurin JDK 21 LTS is highly recommended).
* **Maven:** Version 3.8.1 or higher (Note: Maven Wrapper `mvnw` is not included, so Maven must be installed explicitly on your system).
* **Docker:** Required only if you intend to build and run the application as a container.

## Local Deployment & Startup Steps

These steps are compatible with Windows, macOS, and Linux environments.

### 1. Clone the repository
```bash
git clone <repository_url>
cd <repository_directory>
```
http response
## Run
For local debugging:
```
mvn spring-boot:run -Dspring.profiles.active=local
```
For production, it is need config connection string with mysql database first.
```
mvn spring-boot:run -Dspring.profiles.active=prod
```

## Docker
### Setup
You can specify the base image, entry point, cmd, maintainer and files you want to add to your
image directly in the pom, without needing a separate `Dockerfile`.
If you need `VOLUME` command(or any other not supported dockerfile command), then you will need
to create a `Dockerfile` and use the `dockerDirectory` element.

By default the plugin will try to connect to docker on localhost:2375. Set the DOCKER_HOST
environment variable to connect elsewhere.

DOCKER_HOST=tcp://<host>:2375

Other docker-standard environment variables are honored too such as TLS and certificates.
###Build docker image and run
```
mvn clean package dockerfile:build

### 2. Build the project
Build the application using Maven. You can skip tests during the build if needed.
```bash
mvn clean package -DskipTests
```
if you want to skip unit test:
```
mvn clean package dockerfile:build -DskipTests


### 3. Run the application
Run the application using the Spring Boot Maven plugin. The default application port is `7081`.

**Local Debugging (uses in-memory H2 database):**
```bash
mvn spring-boot:run -Dspring-boot.run.profiles=local
```
or you can build with cli:
```
docker build --build-arg JAR_FILE=*.jar -t megadotnet/springboot-login-application .
*(Alternatively, you can run the built jar: `java -jar target/springboot-login-application-1.0.0.jar`)*

**Production Mode:**
For production, you need to configure the connection string for the MySQL database in the configuration files first.
```bash
mvn spring-boot:run -Dspring-boot.run.profiles=prod
```
Run with H2 database
```
docker run -p 7080:7080 -e "SPRING_PROFILES_ACTIVE=local" -m='2g' --name springboot-login-application -d megadotnet/springboot-login-application

### 4. Docker Deployment (Optional)
Build the Docker image:
```bash
mvn clean package dockerfile:build -DskipTests
```
Run the Docker container:
```bash
docker run -p 7081:7081 -e "SPRING_PROFILES_ACTIVE=local" -m='2g' --name springboot-login-app -d megadotnet/springboot-login-application
```
remote debugging
```
docker run -e "JAVA_OPTS=-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=y" -p 8000:8000 -p 7080:7080 -d megadotnet/springboot-login-application
```

## Project Structure

```text
├── src
│ ├── main
│ │ ├── java/com/app/login # Backend Java source code (Controllers, Services, Repositories, Security, etc.)
│ │ └── resources # Configuration files (application.yml, i18n properties, mails templates)
│ │ └── static # Frontend static resources (AngularJS app, HTML, CSS, JS, Bower components)
│ └── test # Unit and integration tests
├── pom.xml # Maven project object model, managing dependencies and plugins
└── Dockerfile # Docker configuration for containerizing the application
```

## Development Conventions

* **Code Style:** The project uses standard Java coding conventions. Lombok is heavily utilized; ensure your IDE has the Lombok plugin installed and annotation processing enabled.
* **REST API:** All APIs should be designed following RESTful principles and documented using Swagger/OpenAPI.
* **Security:** All endpoints (except public ones like login/register) must be secured. User inputs should be validated using Spring Boot Validation.
* **Testing:** Write unit tests for all business logic. Run `mvn clean test` before any commit to ensure all tests pass.

## Troubleshooting

1. **Port Already in Use:** If the application fails to start because port 7081 is in use, either stop the conflicting process or change the port in `src/main/resources/application.yml` (`server.port: 7081`).
2. **Lombok Compilation Errors:** If you see "cannot find symbol" errors for getters/setters in your IDE, verify that the Lombok plugin is installed and "Enable annotation processing" is checked in your IDE settings.
3. **Database Connection Issues:** When running with the `prod` profile, ensure your MySQL instance is running and the credentials in your configuration file are correct.
Loading