Skip to content

dev_guide.md

Latest commit

 

History

History
107 lines (94 loc) · 5.41 KB

dev_guide.md

File metadata and controls

107 lines (94 loc) · 5.41 KB
Raw

回到首页

项目概览

项目基本信息

  • 名称: strman
  • GroupId (Maven): com.shekhargulati
  • ArtifactId (Maven): strman
  • Version:
  • 主要编程语言: Java

先决条件

  • JDK 版本: 1.8 (根据 Gradle 的 sourceCompatibility 配置)
  • 构建工具版本: Gradle (根据文件内容识别为 Gradle 构建脚本 build.gradle，但未明确指定 Gradle 版本)
  • 其他依赖:
    • JUnit 4.11 (测试依赖)
    • Hamcrest 1.3 (测试依赖)
    • Error Prone (通过插件 net.ltgt.errorprone 引入)
    • Checkstyle (通过 gradle/checkstyle.gradle 引入)
    • Jacoco (代码覆盖率工具，通过插件 jacoco 引入)
    • Maven Publish 和 Signing 插件 (用于发布到 Maven 仓库)
    • ResearchGate Release 插件 (版本管理插件)

构建指南

Gradle 构建

  • 构建命令:
    • 清理构建: ./gradlew clean
    • 编译项目: ./gradlew compileJava
    • 构建项目: ./gradlew build
    • 打包项目: ./gradlew jar
    • 发布到本地 Maven 仓库: ./gradlew publishToMavenLocal
    • 发布到远程仓库: ./gradlew uploadArchives (需要配置 OSS_USER 和 OSS_PASSWORD 环境变量)
    • 生成代码覆盖率报告: ./gradlew jacocoTestReport
  • 构建流程:
    • 该项目使用 Gradle 作为构建工具，配置了 Java 插件、Maven 插件、Maven 发布插件、签名插件、Jacoco 测试覆盖率插件等。
    • 构建流程包括编译源代码、运行测试、生成测试覆盖率报告、打包 JAR 文件（包括主代码、源码和 Javadoc），并可选择发布到 Maven 仓库。
    • 项目配置了 Checkstyle 静态代码分析（通过 gradle/checkstyle.gradle 文件）。
    • 发布到 Maven 仓库时需要提供 Sonatype OSS 的用户名和密码（通过环境变量 OSS_USER 和 OSS_PASSWORD）。
  • 打包目录:
    • 构建输出目录: build/
      • 主代码 JAR: build/libs/<artifactId>-<version>.jar
      • 源码 JAR: build/libs/<artifactId>-<version>-sources.jar
      • Javadoc JAR: build/libs/<artifactId>-<version>-javadoc.jar
    • 测试覆盖率报告:
      • HTML 报告: build/reports/jacoco/test/html/
      • XML 报告: build/reports/jacoco/test/jacocoTestReport.xml

依赖管理

主要依赖

  • 测试依赖:
    • junit:junit:4.11 - 用于单元测试。
    • org.hamcrest:hamcrest-all:1.3 - 用于测试断言和匹配。

添加/修改依赖

  • Gradle: 在 build.gradle 文件的 dependencies { ... } 块中添加依赖，例如 implementation '...', testImplementation '...'。

依赖版本管理

  • Gradle (dependencyManagement 插件或 ext 属性):
    • 在该项目中，依赖版本直接在 dependencies 块中指定，例如 testCompile group: 'junit', name: 'junit', version: '4.11'。
    • 对于更复杂的项目，可以使用 ext 属性或 dependencyManagement 插件来集中管理依赖版本。例如，可以在 ext 块中定义版本号，然后在 dependencies 块中引用这些变量。

工程结构

strman-java/
├── gradlew.bat          # Gradle Windows启动脚本（行业惯例）
├── gradlew              # Gradle Unix启动脚本（行业惯例）
├── .gitignore           # Git忽略规则配置
├── build.gradle         # Gradle项目构建配置（行业惯例）
├── changelog.md         # 版本变更记录
├── gradle.properties    # Gradle属性配置（行业惯例）
├── LICENSE.txt          # 开源许可证文件
├── settings.gradle      # Gradle多模块配置（行业惯例）
├── README.md            # 项目说明文档
├── .travis.yml          # Travis CI持续集成配置
├── gradle/              # Gradle包装器文件目录
│   ├── checkstyle.gradle  # Checkstyle静态检查配置
│   └── wrapper/           # Gradle包装器文件
│       └── gradle-wrapper.properties
├── src/                 # 源代码目录（标准结构）
│   ├── main/            # 主代码
│   │   └── java/        # Java源代码
│   │       └── strman/  # 核心功能包
│   │           ├── Ascii.java      # ASCII相关工具
│   │           ├── Strman.java     # 主工具类（推测）
│   │           └── HtmlEntities.java  # HTML实体处理
│   └── test/            # 测试代码
│       └── java/        # Java测试代码
│           └── strman/  # 测试包
│               └── StrmanTests.java  # 单元测试
├── etc/                 # 附加配置文件目录（推测）
│   ├── checkstyle-exclude.xml  # Checkstyle排除规则
│   └── checkstyle.xml          # Checkstyle主配置
└── .git/                # Git版本控制目录（标准结构）
    ├── hooks/           # Git钩子脚本（含示例）
    ├── refs/            # 引用记录
    │   ├── heads/       # 本地分支
    │   └── remotes/     # 远程分支
    └── objects/         # Git对象存储

命名规约：采用小写短横线风格（如gradle-wrapper），Java包名使用全小写（strman）

分层结构：标准Gradle项目结构，包含main/test代码分离，etc目录存放独立配置。核心功能集中在strman包中，测试与实现1:1对应

扩展设计：通过独立的gradle/和etc目录支持构建/检查工具扩展，.travis.yml体现CI/CD集成能力