From cebeaff0544747d733d240aa3058dec7f7504d55 Mon Sep 17 00:00:00 2001 From: FatttSnake Date: Mon, 11 Dec 2023 14:12:50 +0800 Subject: [PATCH] Add kdoc --- .../controller/system/StatisticsController.kt | 43 ++++++++ .../api/service/system/IStatisticsService.kt | 38 +++++++ .../system/impl/StatisticsServiceImpl.kt | 6 + .../top/fatweb/api/vo/system/CpuInfoVo.kt | 95 ++++++++++++++++ .../fatweb/api/vo/system/FileStoreInfoVo.kt | 30 +++++ .../fatweb/api/vo/system/HardwareInfoVo.kt | 79 ++++++++++++++ .../fatweb/api/vo/system/SoftwareInfoVo.kt | 103 ++++++++++++++++++ .../top/fatweb/api/vo/system/StorageInfoVo.kt | 92 ++++++++++++++++ 8 files changed, 486 insertions(+) diff --git a/src/main/kotlin/top/fatweb/api/controller/system/StatisticsController.kt b/src/main/kotlin/top/fatweb/api/controller/system/StatisticsController.kt index b574272..cbab4c8 100644 --- a/src/main/kotlin/top/fatweb/api/controller/system/StatisticsController.kt +++ b/src/main/kotlin/top/fatweb/api/controller/system/StatisticsController.kt @@ -9,24 +9,67 @@ import top.fatweb.api.entity.common.ResponseResult import top.fatweb.api.service.system.IStatisticsService import top.fatweb.api.vo.system.* +/** + * Statistics controller + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see IStatisticsService + */ @Tag(name = "统计接口", description = "系统信息统计相关接口") @RequestMapping("/system/statistics") @RestController class StatisticsController( private val statisticsService: IStatisticsService ) { + /** + * Get software information + * + * @return Response object includes software information + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ResponseResult + * @see SoftwareInfoVo + */ @Operation(summary = "获取软件信息") @GetMapping("/software") fun software(): ResponseResult = ResponseResult.success(data = statisticsService.software()) + /** + * Get hardware information + * + * @return Response object includes hardware information + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ResponseResult + * @see HardwareInfoVo + */ @Operation(summary = "获取硬件信息") @GetMapping("/hardware") fun hardware(): ResponseResult = ResponseResult.success(data = statisticsService.hardware()) + /** + * Get CPU information + * + * @return Response object includes CPU information + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ResponseResult + * @see CpuInfoVo + */ @Operation(summary = "获取 CPU 信息") @GetMapping("/cpu") fun cpu(): ResponseResult = ResponseResult.success(data = statisticsService.cpu()) + /** + * Get storage information + * + * @return Response object includes storage information + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ResponseResult + * @see StorageInfoVo + */ @Operation(summary = "获取存储信息") @GetMapping("/storage") fun storage(): ResponseResult = ResponseResult.success(data = statisticsService.storage()) diff --git a/src/main/kotlin/top/fatweb/api/service/system/IStatisticsService.kt b/src/main/kotlin/top/fatweb/api/service/system/IStatisticsService.kt index eb18a9e..a6c9397 100644 --- a/src/main/kotlin/top/fatweb/api/service/system/IStatisticsService.kt +++ b/src/main/kotlin/top/fatweb/api/service/system/IStatisticsService.kt @@ -2,12 +2,50 @@ package top.fatweb.api.service.system import top.fatweb.api.vo.system.* +/** + * Statistics service interface + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ interface IStatisticsService { + /** + * Get software information + * + * @return SoftwareInfoVo object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see SoftwareInfoVo + */ fun software(): SoftwareInfoVo + /** + * Get hardware information + * + * @return HardwareInfoVo object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see HardwareInfoVo + */ fun hardware(): HardwareInfoVo + /** + * Get CPU information + * + * @return CpuInfoVo object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see CpuInfoVo + */ fun cpu(): CpuInfoVo + /** + * Get storage information + * + * @return StorageInfoVo object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see StorageInfoVo + */ fun storage(): StorageInfoVo } \ No newline at end of file diff --git a/src/main/kotlin/top/fatweb/api/service/system/impl/StatisticsServiceImpl.kt b/src/main/kotlin/top/fatweb/api/service/system/impl/StatisticsServiceImpl.kt index 3420d7b..ca0c8fc 100644 --- a/src/main/kotlin/top/fatweb/api/service/system/impl/StatisticsServiceImpl.kt +++ b/src/main/kotlin/top/fatweb/api/service/system/impl/StatisticsServiceImpl.kt @@ -12,6 +12,12 @@ import java.time.ZoneOffset import java.util.* import java.util.concurrent.TimeUnit +/** + * Statistics service implement + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ @Service class StatisticsServiceImpl : IStatisticsService { private val systemProperties: Properties = System.getProperties() diff --git a/src/main/kotlin/top/fatweb/api/vo/system/CpuInfoVo.kt b/src/main/kotlin/top/fatweb/api/vo/system/CpuInfoVo.kt index 63fb6fb..26f4993 100644 --- a/src/main/kotlin/top/fatweb/api/vo/system/CpuInfoVo.kt +++ b/src/main/kotlin/top/fatweb/api/vo/system/CpuInfoVo.kt @@ -2,16 +2,111 @@ package top.fatweb.api.vo.system import com.fasterxml.jackson.annotation.JsonInclude +/** + * CPU information value object + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ @JsonInclude(JsonInclude.Include.NON_EMPTY) data class CpuInfoVo( + /** + * Show the percentage of CPU utilization + * that occurred while executing at the user + * level (application). + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val user: Long, + + /** + * Show the percentage of CPU utilization + * that occurred while executing at the user + * level with nice priority. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val nice: Long, + + /** + * Show the percentage of CPU utilization that + * occurred while executing at the system level + * (kernel). Note that this does not include time + * spent servicing hardware and software + * interrupts. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val system: Long, + + /** + * Show the percentage of time that the + * CPU or CPUs were idle and the system did + * not have an outstanding disk I/O request. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val idle: Long, + + /** + * Show the percentage of time that the + * CPU or CPUs were idle during which the + * system had an outstanding disk I/O + * request. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val iowait: Long, + + /** + * Show the percentage of time spent by + * the CPU or CPUs to service hardware + * interrupts. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val irq: Long, + + /** + * Show the percentage of time spent by + * the CPU or CPUs to service software + * interrupts. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val softirq: Long, + + /** + * Show the percentage of time spent in + * involuntary wait by the virtual CPU or CPUs + * while the hypervisor was servicing another + * virtual processor. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val steal: Long, + + /** + * total = user + nice + system + idle + iowait + irq + softirq + steal + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val total: Long, val processors: MutableList? = null + + /** + * List of CPU processors information + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ ) diff --git a/src/main/kotlin/top/fatweb/api/vo/system/FileStoreInfoVo.kt b/src/main/kotlin/top/fatweb/api/vo/system/FileStoreInfoVo.kt index 1d98f86..43cbc0e 100644 --- a/src/main/kotlin/top/fatweb/api/vo/system/FileStoreInfoVo.kt +++ b/src/main/kotlin/top/fatweb/api/vo/system/FileStoreInfoVo.kt @@ -1,7 +1,37 @@ package top.fatweb.api.vo.system +/** + * File storage information value object + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ data class FileStoreInfoVo( + /** + * Mount point of the File System. The + * directory users will normally use to + * interface with the file store. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val mount: String, + + /** + * Total space/capacity of the drive. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val total: Long, + + /** + * Free space on the drive. This space is + * unallocated but may require elevated + * permissions to write. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val free: Long ) diff --git a/src/main/kotlin/top/fatweb/api/vo/system/HardwareInfoVo.kt b/src/main/kotlin/top/fatweb/api/vo/system/HardwareInfoVo.kt index f784ed1..12f5a09 100644 --- a/src/main/kotlin/top/fatweb/api/vo/system/HardwareInfoVo.kt +++ b/src/main/kotlin/top/fatweb/api/vo/system/HardwareInfoVo.kt @@ -1,13 +1,92 @@ package top.fatweb.api.vo.system +/** + * Hardware information value object + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ data class HardwareInfoVo( + /** + * Name of CPU + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val cpu: String, + + /** + * Arch of CPU + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val arch: String, + + /** + * Is CPU 64bit + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val is64Bit: Boolean, + + /** + * Number of packages/sockets in the system. A + * single package may contain multiple cores. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val cpuPhysicalPackageCount: Int, + + /** + * Number of physical CPUs/cores available for + * processing. + * + * On some operating systems with variable numbers + * of physical processors available to the OS, may + * return a max value. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val cpuPhysicalProcessorCount: Int, + + /** + * Number of logical CPUs available for processing. + * This value may be higher than physical CPUs if + * hyperthreading is enabled. + * + * On some operating systems with variable numbers + * of logical processors, may return a max value. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val cpuLogicalProcessorCount: Int, + + /** + * Processor's microarchitecture, if known. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val microarchitecture: String, + + /** + * Memory information overview + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val memories: String, + + /** + * Disk information overview + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val disks: String ) \ No newline at end of file diff --git a/src/main/kotlin/top/fatweb/api/vo/system/SoftwareInfoVo.kt b/src/main/kotlin/top/fatweb/api/vo/system/SoftwareInfoVo.kt index cfebdd8..7eb52ab 100644 --- a/src/main/kotlin/top/fatweb/api/vo/system/SoftwareInfoVo.kt +++ b/src/main/kotlin/top/fatweb/api/vo/system/SoftwareInfoVo.kt @@ -2,19 +2,122 @@ package top.fatweb.api.vo.system import java.time.LocalDateTime +/** + * Software information value object + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ data class SoftwareInfoVo( + /** + * Operating system + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val os: String, + + /** + * Bitness (32 or 64) of the operating system. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val bitness: Int, + + /** + * Version of Java + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val javaVersion: String, + + /** + * Version date of Java + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val javaVersionDate: String, + + /** + * Vendor of Java + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val javaVendor: String, + + /** + * Name of Java runtime + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val javaRuntime: String, + + /** + * Version of Java runtime + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val javaRuntimeVersion: String, + + /** + * Name of Java virtual machine + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val jvm: String, + + /** + * Version of Java virtual machine + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val jvmVersion: String, + + /** + * Version of Java Virtual machine + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val jvmInfo: String, + + /** + * Vendor of Java Virtual machine + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val jvmVendor: String, + + /** + * Version of Java class + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val javaClassVersion: String, + + /** + * Boot time of operating system + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val osBootTime: LocalDateTime, + + /** + * Startup time of server + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val serverStartupTime: LocalDateTime ) diff --git a/src/main/kotlin/top/fatweb/api/vo/system/StorageInfoVo.kt b/src/main/kotlin/top/fatweb/api/vo/system/StorageInfoVo.kt index 1f52758..7362335 100644 --- a/src/main/kotlin/top/fatweb/api/vo/system/StorageInfoVo.kt +++ b/src/main/kotlin/top/fatweb/api/vo/system/StorageInfoVo.kt @@ -1,13 +1,105 @@ package top.fatweb.api.vo.system +/** + * Storage information value object + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ data class StorageInfoVo( + /** + * The amount of actual physical memory. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val memoryTotal: Long, + + /** + * The amount of physical memory currently + * available。 + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val memoryFree: Long, + + /** + * The maximum memory that can be committed by the + * system without extending the paging file(s). Also called the + * Commit Limit. If the paging/swap file can be extended, this + * is a soft limit. This is generally equal to the sum of the sizes + * of physical memory and paging/swap file(s). + * + * On Linux, represents the total amount of memory currently + * available to be allocated on the system based on the + * overcommit ratio, identified as CommitLimit. This may be + * higher or lower than the total size of physical and swap + * memory depending on system configuration. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val virtualMemoryMax: Long, + + /** + * The memory currently committed by the system, in + * bytes. Also called the Commit Total. This is generally + * equal to the sum of the bytes used of physical + * memory and paging/swap file(s). + * + * On Windows, committing pages changes this value + * immediately; however, the physical memory is not + * charged until the pages are accessed, so this + * value may exceed the sum of used physical and + * paging/swap file memory. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val virtualMemoryInUse: Long, + + /** + * The current size of the paging/swap + * file(s). If the paging/swap file can be + * extended, this is a soft limit. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val swapTotal: Long, + + /** + * The current memory committed to the + * paging/swap file(s). + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val swapUsed: Long, + + /** + * Total amount of memory in the Java virtual machine. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val jvmTotal: Long, + + /** + * Amount of free memory in the Java Virtual Machine. + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ val jvmFree: Long, + + /** + * List of FileStoreInfoVo object + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see FileStoreInfoVo + */ val fileStores: List )