onixbyte/onixbyte.com
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: rename projects to opensource-projects

Browse Source 
Frees /products/ for the product page and makes the open-source archive
explicit, rather than leaving two sections that both look like "projects".

- Move the directory in both locales and update the 18 internal links
  pointing into it.
- Rework helix for the GitHub layout: server/ and web/ are directories in
  a single repository there, not the two separate repositories Gitea had.
  The "fork both repositories" step and the section wording follow.
- Correct helix's stated Java version to 21, which is what the build
  actually targets.
This commit is contained in:
zihluwang committed 2026-09-25 14:48:38 +08:00
1 parent 29f7411da5
commit b2eb6b9638
30 files changed
+75 -71
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/zh-hans/opensource-projects/calendar-toolbox/api.md
+390
View File
@@ -0,0 +1,390 @@
---
title: Calendar Toolbox API
---
## 包结构概览
库的代码组织在基础包 `com.onixbyte.calendar` 下，结构如下：
| 包 | 描述 |
|---|---|
| `com.onixbyte.calendar` | 根日历对象 |
| `com.onixbyte.calendar.component` | iCalendar 组件（VEVENT、VTODO 等） |
| `com.onixbyte.calendar.component.property` | 组件级属性 |
| `com.onixbyte.calendar.property` | 日历级属性 |
| `com.onixbyte.calendar.parameter` | iCalendar 属性参数 |
| `com.onixbyte.calendar.recurrence` | 重复规则类型 |
| `com.onixbyte.calendar.value` | 值类型 |
| `com.onixbyte.calendar.util` | 格式化工具类 |
---
## Calendar
表示 iCalendar（RFC 5545）VCALENDAR 容器的顶层对象。
```java
Calendar calendar = Calendar.builder()
.withCalendarScale(...)
.withMethod(...)
.withProductIdentifier(...)
.withVersion(...)
.withOwner(...)
.withPrimaryCalendar(...)
.withPublishedTTL(...)
.withCalendarDescription(...)
.withCalendarName(...)
.withCalendarId(...)
.withCustomProperties(...)
.withComponents(event, todo, ...)
.build();
String icsContent = calendar.formatted();
```
### 日历属性
所有日历级属性位于 `com.onixbyte.calendar.property`，实现 `CalendarProperty` 接口。
| 类 | iCalendar 属性 | 描述 |
|---|---|---|
| `CalendarScale` | `CALSCALE` | 日历系统（例如 GREGORIAN） |
| `Method` | `METHOD` | iCalendar 方法（例如 PUBLISH、REQUEST） |
| `ProductIdentifier` | `PRODID` | 日历的产品标识符 |
| `Version` | `VERSION` | iCalendar 版本（例如 2.0） |
| `Owner` | `X-OWNER` | 日历所有者 |
| `PrimaryCalendar` | `X-PRIMARY-CALENDAR` | 是否为主日历 |
| `PublishedTTL` | `X-PUBLISHED-TTL` | 已发布日历的生存时间 |
| `CalendarDescription` | `X-CALENDAR-DESC` | 日历描述 |
| `CalendarName` | `X-CALENDAR-NAME` | 日历名称 |
| `CalendarId` | `X-CALENDAR-ID` | 日历标识符 |
| `CustomCalendarProperty` | `X-*` | 自定义日历属性 |
自定义属性使用 Builder 创建：
```java
var customProp = CustomCalendarProperty.builder()
.withParameters(...)
.build("X-MY-PROPERTY", "my-value");
```
> 注意：自定义属性名称**必须**以 `X-` 开头。
---
## 组件
组件是 iCalendar 对象的核心实体。每个组件实现 `CalendarComponent` 接口，并在 `BEGIN:TYPE` 和 `END:TYPE` 定界符之间渲染。
### Event（VEVENT）
表示一个预定的活动/事件。
```java
Event event = Event.builder()
.withDateTimeStamp(dtstamp) // 必需
.withUniqueIdentifier(uid) // 必需
.withDateTimeStart(dtstart)
.withDateTimeEnd(dtend) // 与 duration 互斥
.withDuration(duration) // 与 dtend 互斥
.withSummary(summary)
.withDescription(description)
.withClassification(classification)
.withDateTimeCreated(dateTimeCreated)
.withGeographicPosition(geoPos)
.withLastModified(lastModified)
.withLocation(location)
.withOrganiser(organiser)
.withPriority(priority)
.withSequenceNumber(seqNumber)
.withStatus(status)
.withTimeTransparency(transparency)
.withUniformResourceLocator(url)
.withRecurrenceId(recurrenceId)
.withRecurrenceRule(rrule)
.withAttachments(attachments)
.withAttendees(attendees)
.withCategories(categories)
.withComments(comments)
.withContacts(contacts)
.withExceptionDateTimes(exDates)
.withRequestStatuses(statuses)
.withRelated(related)
.withResources(resources)
.withRecurrenceDateTimes(rDates)
.build();
```
### Todo（VTODO）
表示待办事项或任务。
```java
Todo todo = Todo.builder()
.withDateTimeStamp(dtstamp) // 必需
.withUniqueIdentifier(uid) // 必需
.withSummary(summary)
.withDateTimeStart(dtstart)
.withDateTimeDue(due) // 与 duration 互斥
.withDuration(duration) // 与 due 互斥
.withDateTimeCompleted(completed)
.withPercentComplete(percent)
.withClassification(classification)
.withDateTimeCreated(created)
.withDescription(description)
.withGeographicPosition(geoPos)
.withLastModified(lastModified)
.withLocation(location)
.withOrganiser(organiser)
.withPriority(priority)
.withSequenceNumber(seq)
.withStatus(status)
.withRecurrenceId(recurId)
.withRecurrenceRule(rrule)
.withUniformResourceLocator(url)
.withAttachments(attachments)
.withAttendees(attendees)
.withCategories(categories)
.withComments(comments)
.withContacts(contacts)
.withExceptionDateTimes(exDates)
.withRequestStatuses(statuses)
.withRelatedToList(related)
.withResources(resources)
.withRecurrenceDateTimes(rDates)
.build();
```
### Journal（VJOURNAL）
表示日记条目或笔记。
```java
Journal journal = Journal.builder()
.withDateTimeStamp(dtstamp) // 必需
.withUniqueIdentifier(uid) // 必需
.withSummary(summary)
.withClassification(classification)
.withDateTimeCreated(created)
.withDateTimeStart(dtstart)
.withLastModified(lastModified)
.withOrganiser(organiser)
.withRecurrenceId(recurId)
.withSequenceNumber(seq)
.withStatus(status)
.withUniformResourceLocator(url)
.withRecurrenceRule(rrule)
.withAttachments(attachments)
.withAttendees(attendees)
.withCategories(categories)
.withComments(comments)
.withContacts(contacts)
.withDescriptions(descriptions)
.withExceptionDateTimes(exDates)
.withRelatedToList(related)
.withRecurrenceDate(rDates)
.withRequestStatuses(statuses)
.build();
```
### FreeBusy（VFREEBUSY）
表示空闲/忙碌时间信息。
```java
FreeBusy freeBusy = FreeBusy.builder()
.withDateTimeStamp(dtstamp) // 必需
.withUniqueIdentifier(uid) // 必需
.withContact(contact)
.withDateTimeStart(dtstart)
.withDateTimeEnd(dtend)
.withOrganiser(organiser)
.withUniformResourceLocator(url)
.withAttendees(attendees)
.withComments(comments)
.withFreeBusyTimes(freeBusyTimes)
.withRequestStatuses(statuses)
.build();
```
### TimeZone（VTIMEZONE）
定义时区规则，包括标准时间和夏令时转换。
```java
TimeZone timezone = TimeZone.builder()
.withTimeZoneIdentifier(tzId)
.withLastModified(lastModified)
.withTimeZoneUrl(tzUrl)
.withTimeZoneProperties(standardProp, daylightProp)
.build();
```
时区属性定义实际的转换规则：
```java
TimeZoneProperty standard = TimeZoneProperty.builder()
.withDateTimeStart(dtstart)
.withTimeZoneOffsetTo(offsetTo)
.withTimeZoneOffsetFrom(offsetFrom)
.withRecurrenceRule(rrule)
.withTimeZoneNames(tzName)
.buildStandard(); // 或 buildDaylight()
TimeZoneProperty daylight = TimeZoneProperty.builder()
.withDateTimeStart(dtstart)
.withTimeZoneOffsetTo(offsetTo)
.withTimeZoneOffsetFrom(offsetFrom)
.buildDaylight();
```
### Alarm（VALARM）
定义闹钟/提醒通知。支持三种闹钟类型：
```java
// 音频闹钟
Alarm audioAlarm = Alarm.builder()
.withTrigger(trigger)
.withDuration(duration)
.withRepeatCount(repeatCount)
.withAttachments(audioAttachment)
.buildAudio();
// 显示闹钟
Alarm displayAlarm = Alarm.builder()
.withTrigger(trigger)
.withDescription(description) // 必需
.withDuration(duration)
.withRepeatCount(repeatCount)
.buildDisplay();
// 邮件闹钟
Alarm emailAlarm = Alarm.builder()
.withTrigger(trigger)
.withDescription(description) // 必需
.withSummary(summary) // 必需
.withAttendees(attendees) // 必需
.withDuration(duration)
.withRepeatCount(repeatCount)
.buildEmail();
```
---
## 组件属性
组件属性位于 `com.onixbyte.calendar.component.property`，实现 `ComponentProperty` 接口。
| 类 | iCalendar 属性 | 描述 |
|---|---|---|
| `Action` | `ACTION` | 闹钟操作类型（AUDIO、DISPLAY、EMAIL） |
| `Attachment` | `ATTACH` | 文档附件 |
| `Attendee` | `ATTENDEE` | 事件/任务参与者 |
| `Categories` | `CATEGORIES` | 类别或标签 |
| `Classification` | `CLASS` | 访问分类（PUBLIC、PRIVATE、CONFIDENTIAL） |
| `Comment` | `COMMENT` | 评论 |
| `Contact` | `CONTACT` | 联系信息 |
| `DateTimeCompleted` | `COMPLETED` | 完成日期时间 |
| `DateTimeCreated` | `CREATED` | 创建日期时间 |
| `DateTimeDue` | `DUE` | 截止日期时间 |
| `DateTimeEnd` | `DTEND` | 结束日期时间 |
| `DateTimeStamp` | `DTSTAMP` | 日期时间戳 |
| `DateTimeStart` | `DTSTART` | 开始日期时间 |
| `Description` | `DESCRIPTION` | 描述 |
| `ExceptionDateTimes` | `EXDATE` | 例外日期时间 |
| `FreeBusyTime` | `FREEBUSY` | 空闲/忙碌时间段 |
| `GeographicPosition` | `GEO` | 地理位置（纬度/经度） |
| `LastModified` | `LAST-MODIFIED` | 最后修改日期时间 |
| `Location` | `LOCATION` | 地点 |
| `Organiser` | `ORGANIZER` | 组织者 |
| `PercentComplete` | `PERCENT-COMPLETE` | 完成百分比 |
| `Priority` | `PRIORITY` | 优先级 |
| `RecurrenceDateTimes` | `RDATE` | 重复日期时间 |
| `RecurrenceId` | `RECURRENCE-ID` | 重复实例标识符 |
| `RecurrenceRule` | `RRULE` | 重复规则 |
| `RelatedTo` | `RELATED-TO` | 相关组件引用 |
| `RepeatCount` | `REPEAT` | 闹钟重复次数 |
| `RequestStatus` | `REQUEST-STATUS` | 请求状态 |
| `Resources` | `RESOURCES` | 资源 |
| `SequenceNumber` | `SEQUENCE` | 序列号（修订版本） |
| `Status` | `STATUS` | 组件状态（TENTATIVE、CONFIRMED、CANCELLED 等） |
| `Summary` | `SUMMARY` | 标题或摘要 |
| `TimeTransparency` | `TRANSP` | 时间透明度（OPAQUE、TRANSPARENT） |
| `TimeZoneIdentifier` | `TZID` | 时区标识符 |
| `TimeZoneName` | `TZNAME` | 时区名称 |
| `TimeZoneOffsetFrom` | `TZOFFSETFROM` | 相对于 UTC 的时区偏移（原） |
| `TimeZoneOffsetTo` | `TZOFFSETTO` | 相对于 UTC 的时区偏移（目标） |
| `TimeZoneUrl` | `TZURL` | 时区 URL |
| `Trigger` | `TRIGGER` | 闹钟触发器 |
| `UniformResourceLocator` | `URL` | 关联 URL |
| `UniqueIdentifier` | `UID` | 唯一标识符 |
| `CustomComponentProperty` | `X-*` | 自定义组件属性 |
---
## 参数
参数位于 `com.onixbyte.calendar.parameter`，为组件属性提供额外限定。
| 类 | iCalendar 参数 | 描述 |
|---|---|---|
| `AlarmTriggerRelationship` | `RELATED` | 触发器关联（START、END） |
| `AlternateTextRepresentation` | `ALTREP` | 替代文本 URI |
| `CalendarUserType` | `CUTYPE` | 日历用户类型（INDIVIDUAL、GROUP、RESOURCE 等） |
| `CommonName` | `CN` | 通用名称 |
| `Delegatees` | `DELEGATED-TO` | 受托人 |
| `Delegators` | `DELEGATED-FROM` | 委托人 |
| `DirectoryEntryReference` | `DIR` | 目录条目 URI |
| `FormatType` | `FMTTYPE` | 格式类型（MIME 类型） |
| `FreeBusyTimeType` | `FBTYPE` | 空闲/忙碌时间类型 |
| `InlineEncoding` | `ENCODING` | 内联编码（BASE64） |
| `Language` | `LANGUAGE` | 语言 |
| `Membership` | `MEMBER` | 组成员 |
| `ParticipationRole` | `ROLE` | 参与角色（CHAIR、REQ-PARTICIPANT 等） |
| `ParticipationStatus` | `PARTSTAT` | 参与状态（ACCEPTED、DECLINED 等） |
| `RecurrenceIdentifierRange` | `RANGE` | 重复范围（THISANDPRIOR、THISANDFUTURE） |
| `RelationshipType` | `RELTYPE` | 关系类型（PARENT、CHILD、SIBLING） |
| `RsvpExpectation` | `RSVP` | RSVP 期望（TRUE、FALSE） |
| `SentBy` | `SENT-BY` | 发送者 |
| `TimeZoneIdentifier` | `TZID` | 时区标识符 |
| `ValueDataType` | `VALUE` | 值数据类型（DATE、DATE-TIME 等） |
---
## 递归类型
位于 `com.onixbyte.calendar.recurrence`。
| 类 | 描述 |
|---|---|
| `Frequency` | 重复频率常量（DAILY、WEEKLY、MONTHLY、YEARLY），用于重复规则 |
| `WeekdayNum` | 重复规则的星期序号（例如第 2 个星期一） |
---
## 值类型
位于 `com.onixbyte.calendar.value`。
| 类 | 描述 |
|---|---|
| `FreeBusyTimeValue` | 表示空闲/忙碌时间值 |
| `PeriodOfTime` | 表示一个时间段，包含开始和结束 |
| `PropertyValue` | 属性的基础值类型 |
| `UtcOffset` | UTC 偏移值（例如 `-05:00`、`+01:00`） |
---
## 格式化输出
所有组件和属性都提供 `formatted()` 方法，返回符合 iCalendar 规范的字符串。`Calendar.formatted()` 方法生成完整的 `.ics` 输出，包含 `BEGIN:VCALENDAR`/`END:VCALENDAR`。
```java
String ics = calendar.formatted();
// BEGIN:VCALENDAR
// CALSCALE:GREGORIAN
// METHOD:PUBLISH
// ...
// END:VCALENDAR
```
docs/zh-hans/opensource-projects/calendar-toolbox/index.mdx
+102
View File
@@ -0,0 +1,102 @@
---
title: Calendar Toolbox
---
import { Tabs, Tab } from "@rspress/core/theme"
## 介绍
Calendar Toolbox 是一个 Java 库，旨在简化遵循 iCalendar 规范（RFC 5545）的 `.ics` 文件的创建。该库为开发者提供了简洁的 API，可生成能够导入到 Microsoft Outlook、Google Calendar 和 Apple Calendar 等主流日历应用程序中的日历事件。
通过 Calendar Toolbox，您可以以编程方式轻松创建、定制和导出日历事件文件，从而以最少的代价将日历功能集成到您的 Java 应用中。
## 特性
- **完整 RFC 5545 兼容** — 支持 VEVENT、VTODO、VJOURNAL、VFREEBUSY、VTIMEZONE 和 VALARM 等标准 iCalendar 组件。
- **流式 Builder 模式** — 所有组件和属性均使用 Builder 模式，构建过程可读性强且直观。
- **类型安全属性** — 强类型的属性和参数确保编译期正确性。
- **自定义扩展** — 支持日历级和组件级的自定义 `X-` 属性。
- **轻量级** — 核心功能零外部依赖。
## 安装
<Tabs>
<Tab label="Gradle with Kotlin DSL">
```kotlin title="build.gradle.kts"
dependencies {
implementation("com.onixbyte:calendar-toolbox:1.1.0")
}
```
</Tab>
<Tab label="Maven">
```xml title="pom.xml"
<dependencies>
<dependency>
<groupId>com.onixbyte</groupId>
<artifactId>calendar-toolbox</artifactId>
<version>1.1.0</version>
</dependency>
</dependencies>
```
</Tab>
</Tabs>
## 快速开始
```java
import com.onixbyte.calendar.Calendar;
import com.onixbyte.calendar.component.Event;
import com.onixbyte.calendar.component.property.*;
import com.onixbyte.calendar.property.*;
import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
public class CalendarExample {
public static void main(String[] args) {
// 创建所需的日期时间属性
var now = ZonedDateTime.now(ZoneOffset.UTC);
var dtstamp = DateTimeStamp.of(now);
var uid = UniqueIdentifier.of("meeting-001@example.com");
var dtstart = DateTimeStart.of(
LocalDateTime.of(2025, 8, 15, 9, 0),
"America/New_York"
);
var dtend = DateTimeEnd.of(
LocalDateTime.of(2025, 8, 15, 10, 0),
"America/New_York"
);
var summary = Summary.of("Team Standup");
var description = Description.of("Daily team standup meeting.");
// 构建事件
var event = Event.builder()
.withDateTimeStamp(dtstamp)
.withUniqueIdentifier(uid)
.withDateTimeStart(dtstart)
.withDateTimeEnd(dtend)
.withSummary(summary)
.withDescription(description)
.build();
// 构建日历并输出 .ics 内容
var calendar = Calendar.builder()
.withCalendarScale(CalendarScale.of("GREGORIAN"))
.withMethod(Method.of("PUBLISH"))
.withProductIdentifier(ProductIdentifier.of("-//OnixByte//Calendar Toolbox//EN"))
.withVersion(Version.of("2.0"))
.withComponents(event)
.build();
System.out.println(calendar.formatted());
}
}
```
上述代码会生成一个 `.ics` 格式的字符串，可以保存为文件或通过邮件发送。
## 许可证
Calendar Toolbox 是采用 MIT 许可证发布的开源软件。
docs/zh-hans/opensource-projects/captcha/api.md
+248
View File
@@ -0,0 +1,248 @@
---
title: Captcha API
---
## 包结构概览
库的代码组织在基础包 `com.onixbyte.captcha` 下，结构如下：
| 包 | 描述 |
|---|---|
| `com.onixbyte.captcha` | 核心接口 |
| `com.onixbyte.captcha.impl` | 默认实现 |
| `com.onixbyte.captcha.text` | 文本生成器和渲染器接口 |
| `com.onixbyte.captcha.text.impl` | 文本生成器和渲染器实现 |
| `com.onixbyte.captcha.text.enums` | 文本相关枚举 |
| `com.onixbyte.captcha.background` | 背景生成器接口 |
| `com.onixbyte.captcha.background.impl` | 背景生成器实现 |
| `com.onixbyte.captcha.noise` | 噪点生成器接口 |
| `com.onixbyte.captcha.noise.impl` | 噪点生成器实现 |
| `com.onixbyte.captcha.gimpy` | 扭曲引擎接口 |
| `com.onixbyte.captcha.gimpy.impl` | 扭曲引擎实现 |
---
## Producer
负责创建 CAPTCHA 图片并在其上绘制文字的顶层接口。
```java
Producer captcha = DefaultCaptchaProducer.builder()
.textProducer(textProducer)
.wordRenderer(wordRenderer)
.gimpyEngine(gimpyEngine)
.backgroundProducer(backgroundProducer)
.width(200)
.height(50)
.borderDrawn(true)
.borderColour(Color.BLACK)
.borderThickness(1)
.build();
String text = captcha.createText();
BufferedImage image = captcha.createImage(text);
```
### DefaultCaptchaProducer Builder
| 方法 | 默认值 | 描述 |
|---|---|---|
| `textProducer` | `DefaultTextProducer.builder().build()` | 文本生成器 |
| `wordRenderer` | `DefaultWordRenderer.builder().build()` | 文字渲染器 |
| `gimpyEngine` | `WaterRipple.builder().build()` | 扭曲引擎 |
| `backgroundProducer` | `DefaultBackgroundProducer.builder().build()` | 背景生成器 |
| `width` | `200` | 验证码图片宽度 |
| `height` | `50` | 验证码图片高度 |
| `borderDrawn` | `true` | 是否绘制边框 |
| `borderColour` | `Color.BLACK` | 边框颜色 |
| `borderThickness` | `1` | 边框厚度 |
---
## Text
### TextProducer
用于创建 CAPTCHA 文本字符串的接口。
```java
public interface TextProducer {
String getText();
}
```
#### DefaultTextProducer
生成可配置长度和字符集的随机文本。
```java
DefaultTextProducer textProducer = DefaultTextProducer.builder()
.length(6) // 默认: 6
.chars("ABCDEFGHIJKLMNOPQRSTUVWXYZ".toCharArray()) // 默认: a-z, A-Z, 0-9
.build();
```
| 方法 | 默认值 | 描述 |
|---|---|---|
| `length` | `6` | 生成文本的长度 |
| `chars` | `a-z`、`A-Z`、`0-9`（共 62 个字符） | 生成文本使用的字符集 |
### WordRenderer
将文字渲染到图片上的接口。
```java
public interface WordRenderer {
BufferedImage renderWord(String word, int width, int height);
}
```
#### DefaultWordRenderer
使用可配置的字体、颜色和间距渲染文字。
```java
DefaultWordRenderer wordRenderer = DefaultWordRenderer.builder()
.fontSize(40) // 默认: 40
.fonts("Arial", "Courier") // 默认: Arial, Courier
.fontColour(Color.BLACK) // 默认: Color.BLACK
.charSpace(2) // 默认: 2
.fontStyle(FontStyle.BOLD) // 默认: FontStyle.BOLD
.build();
```
| 方法 | 默认值 | 描述 |
|---|---|---|
| `fontSize` | `40` | 字号（像素） |
| `fonts` | `["Arial", "Courier"]` | 字体族（随机选择） |
| `fontColour` | `Color.BLACK` | 字体颜色 |
| `charSpace` | `2` | 字符间距（像素） |
| `fontStyle` | `FontStyle.BOLD` | 字体样式 |
### FontStyle
定义 CAPTCHA 文字渲染支持的字体样式。
| 值 | 对应的 AWT 常量 | 描述 |
|---|---|---|
| `PLAIN` | `java.awt.Font.PLAIN` | 普通样式 |
| `BOLD` | `java.awt.Font.BOLD` | 粗体 |
| `ITALIC` | `java.awt.Font.ITALIC` | 斜体 |
| `BOLD_ITALIC` | `java.awt.Font.BOLD | Font.ITALIC` | 粗斜体 |
---
## GimpyEngine
用于对图片应用扭曲效果的接口。
```java
public interface GimpyEngine {
BufferedImage getDistortedImage(BufferedImage baseImage);
}
```
### WaterRipple
应用水波纹扭曲效果。继承 `AbstractGimpyEngine`，自动添加噪点。
```java
WaterRipple gimpy = WaterRipple.builder()
.noiseProducer(DefaultNoiseProducer.builder().build()) // 默认: DefaultNoiseProducer
.build();
```
| 方法 | 默认值 | 描述 |
|---|---|---|
| `noiseProducer` | `DefaultNoiseProducer.builder().build()` | 噪点生成器 |
### FishEyeGimpy
应用鱼眼扭曲效果，在图片上绘制水平和垂直线条。
```java
FishEyeGimpy gimpy = FishEyeGimpy.builder()
.build();
```
### ShadowGimpy
应用阴影和波纹效果。继承 `AbstractGimpyEngine`，自动添加噪点。
```java
ShadowGimpy gimpy = ShadowGimpy.builder()
.noiseProducer(DefaultNoiseProducer.builder().build()) // 默认: DefaultNoiseProducer
.build();
```
| 方法 | 默认值 | 描述 |
|---|---|---|
| `noiseProducer` | `DefaultNoiseProducer.builder().build()` | 噪点生成器 |
---
## Noise
### NoiseProducer
向图片添加噪点的接口。
```java
public interface NoiseProducer {
void makeNoise(BufferedImage image, float factorOne, float factorTwo,
float factorThree, float factorFour);
}
```
#### DefaultNoiseProducer
使用可配置的颜色添加噪点曲线。
```java
DefaultNoiseProducer noise = DefaultNoiseProducer.builder()
.noiseColour(Color.BLACK) // 默认: Color.BLACK
.build();
```
| 方法 | 默认值 | 描述 |
|---|---|---|
| `noiseColour` | `Color.BLACK` | 噪点颜色 |
#### NoNoiseProducer
不向图片添加任何噪点的空实现。
```java
NoiseProducer noise = NoNoiseProducer.builder()
.build();
```
---
## Background
### BackgroundProducer
向图片添加背景的接口。
```java
public interface BackgroundProducer {
BufferedImage addBackground(BufferedImage image);
}
```
#### DefaultBackgroundProducer
创建具有可配置起始和结束颜色的渐变背景。
```java
DefaultBackgroundProducer background = DefaultBackgroundProducer.builder()
.colourFrom(Color.WHITE) // 默认: Color.LIGHT_GRAY
.colourTo(Color.LIGHT_GRAY) // 默认: Color.WHITE
.build();
```
| 方法 | 默认值 | 描述 |
|---|---|---|
| `colourFrom` | `Color.LIGHT_GRAY` | 渐变起始颜色 |
| `colourTo` | `Color.WHITE` | 渐变结束颜色 |
docs/zh-hans/opensource-projects/captcha/index.mdx
+89
View File
@@ -0,0 +1,89 @@
---
title: Captcha
---
import { Tabs, Tab } from "@rspress/core/theme"
## 介绍
Captcha 是一个用于生成 CAPTCHA 验证码图片的 Java 库。本项目是 Google Kaptcha 的精神继承者，按照现代开发实践进行了现代化改造。
通过 Captcha，您可以轻松生成可定制的 CAPTCHA 图片，支持多种扭曲效果、噪点和背景选项，轻松集成到您的 Java 应用中。
## 特性
- **易于集成** — 基于 Builder 的简洁 API，快速完成配置和集成。
- **可定制的验证码生成** — 配置文本长度、字符集、字体样式和颜色。
- **多种扭曲效果** — 支持水波纹、鱼眼和阴影效果。
- **可配置噪点** — 使用自定义颜色添加噪点线条，或完全禁用噪点。
- **渐变背景** — 可自定义的渐变背景颜色。
- **简洁现代的代码** — 文档完善、类型安全且易于扩展。
## 安装
<Tabs>
<Tab label="Gradle with Kotlin DSL">
```kotlin title="build.gradle.kts"
dependencies {
implementation("com.onixbyte:captcha:1.0.0")
}
```
</Tab>
<Tab label="Maven">
```xml title="pom.xml"
<dependencies>
<dependency>
<groupId>com.onixbyte</groupId>
<artifactId>captcha</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
```
</Tab>
</Tabs>
## 快速开始
```java
import com.onixbyte.captcha.Producer;
import com.onixbyte.captcha.background.BackgroundProducer;
import com.onixbyte.captcha.background.impl.DefaultBackgroundProducer;
import com.onixbyte.captcha.gimpy.GimpyEngine;
import com.onixbyte.captcha.gimpy.impl.WaterRipple;
import com.onixbyte.captcha.impl.DefaultCaptchaProducer;
import com.onixbyte.captcha.noise.NoiseProducer;
import com.onixbyte.captcha.noise.impl.DefaultNoiseProducer;
import com.onixbyte.captcha.text.TextProducer;
import com.onixbyte.captcha.text.WordRenderer;
import com.onixbyte.captcha.text.impl.DefaultTextProducer;
import com.onixbyte.captcha.text.impl.DefaultWordRenderer;
import javax.imageio.ImageIO;
import java.awt.*;
import java.awt.image.BufferedImage;
import java.io.File;
import java.io.IOException;
public class CaptchaExample {
public static void main(String[] args) throws IOException {
// 使用默认配置创建 CAPTCHA 生产者
Producer captcha = DefaultCaptchaProducer.builder().build();
// 生成文本并创建图片
String captchaText = captcha.createText();
BufferedImage captchaImage = captcha.createImage(captchaText);
// 保存图片到文件
ImageIO.write(captchaImage, "png", new File("captcha.png"));
System.out.println("CAPTCHA 文本: " + captchaText);
}
}
```
以上代码生成一张包含 6 位随机字符的 CAPTCHA 图片，并将其保存为 PNG 文件。
## 许可证
Captcha 是采用 MIT 许可证发布的开源软件。
docs/zh-hans/opensource-projects/claude-code-skill-manager/index.mdx
+216
View File
@@ -0,0 +1,216 @@
---
title: Claude Code Skills Manager
---
import { Tabs, Tab } from "@rspress/core/theme"
## 介绍
Claude Code Skills Manager（`ccsm`）是一个 CLI 工具，用于从基于 Git 的 Marketplace 仓库中发现、安装和管理 Claude Code Skills。你可以将任何公开的、包含 `skills.json` 清单的 Git 仓库注册为 Skill 来源，然后通过统一的命令行界面搜索、安装、更新和移除 Skills。
Skills 会被直接部署到 Claude Code 自身的 Skills 目录（`~/.claude/skills/`）中，Claude Code 启动时会自动加载。
## 安装
<Tabs>
<Tab label="预编译二进制">
从 [Releases 页面](https://onixbyte.dev/onixbyte/claude-code-skill-manager/releases) 下载对应平台的最新二进制文件。
| 平台 | 二进制文件 |
|------|-----------|
| Linux (amd64) | `ccsm-linux-amd64` |
| macOS (amd64) | `ccsm-darwin-amd64` |
| Windows (amd64) | `ccsm-windows-amd64.exe` |
将二进制文件放到 `PATH` 中的某个目录，并重命名为 `ccsm`（Windows 上为 `ccsm.exe`）。
</Tab>
<Tab label="Cargo 安装">
```bash
git clone https://onixbyte.dev/onixbyte/claude-code-skill-manager.git
cd claude-code-skill-manager
cargo install --path .
```
需要 Rust 工具链（通过 [rustup.rs](https://rustup.rs) 安装）。
</Tab>
<Tab label="从源码构建">
```bash
git clone https://onixbyte.dev/onixbyte/claude-code-skill-manager.git
cd claude-code-skill-manager
cargo build --release
```
二进制文件位于 `target/release/ccsm`（Windows 上为 `ccsm.exe`）。
</Tab>
</Tabs>
## 快速开始
### 注册 Marketplace
Marketplace 可以是任何在根目录包含 `skills.json` 清单的公开 Git 仓库。通过以下命令注册：
```bash
ccsm marketplace add https://github.com/example/skills
```
CCSM 会拉取清单并缓存到本地。你可以根据需要注册任意数量的 Marketplace。
### 浏览和安装 Skills
```bash
# 搜索所有已注册 Marketplace 中的 Skills
ccsm search
# 通过关键词过滤
ccsm search git
# 按名称安装 Skill
ccsm install my-awesome-skill
# 如果多个 Marketplace 中存在同名 Skill，可指定 Marketplace
ccsm install my-skill --marketplace my-marketplace
```
### 管理已安装的 Skills
```bash
# 列出已安装的 Skills
ccsm list
# 查看已安装 Skill 的详细信息
ccsm info my-awesome-skill
# 更新所有已安装的 Skills 到最新版本
ccsm update
# 更新指定 Skill
ccsm update my-awesome-skill
# 移除 Skill
ccsm remove my-awesome-skill
```
### Marketplace 管理
```bash
# 列出所有已注册的 Marketplace
ccsm marketplace list
# 刷新缓存的清单（所有 Marketplace）
ccsm marketplace update
# 刷新指定 Marketplace
ccsm marketplace update my-marketplace
# 移除 Marketplace
ccsm marketplace remove my-marketplace
```
### 安装模式
CCSM 支持两种部署模式：
| 模式 | 行为 | 适用场景 |
|------|------|----------|
| `copy`（默认） | 将文件物理复制到 `~/.claude/skills/<name>/` | 日常使用 — 安全且自包含 |
| `link` | 创建指向本地存储的符号链接 | Skill 开发 — 对源文件的修改会立即生效 |
可在配置中设置默认模式，也可在安装时单独指定：
```bash
ccsm install my-skill --link
```
## 自建 Skill Marketplace
Marketplace 本质上就是一个包含 `skills.json` 清单的公开 Git 仓库。不需要服务器组件，不需要认证，也不需要 API 密钥 —— CCSM 会直接从 Git 托管平台的 raw 文件端点读取清单。
### Marketplace 仓库结构
```
your-marketplace-repo/
skills.json # 必需：清单文件
README.md # 可选
```
### `skills.json` 清单格式
```json
{
"name": "My Marketplace",
"version": "1.0.0",
"skills": [
{
"name": "my-skill",
"description": "在搜索结果中显示的简短描述",
"repository": "https://github.com/user/skill-repo",
"branch": "main"
},
{
"name": "another-skill",
"description": "位于 monorepo 子目录中的 Skill",
"repository": "https://github.com/user/monorepo",
"branch": "main",
"path": "skills/another-skill"
}
]
}
```
**顶层字段：**
| 字段 | 必需 | 说明 |
|------|------|------|
| `name` | 是 | Marketplace 的显示名称 |
| `version` | 否 | 用于自行追踪的任意版本号 |
| `skills` | 否 | Skill 条目数组（默认为 `[]`） |
**Skill 条目字段：**
| 字段 | 必需 | 说明 |
|------|------|------|
| `name` | 是 | Skill 的唯一标识符（用于 `ccsm install <name>`） |
| `description` | 是 | 在 `ccsm search` 输出中显示的一行摘要 |
| `repository` | 是 | Skill 的公开 Git 仓库 URL |
| `branch` | 否 | 安装时使用的 Git 分支（先尝试 `main`，再回退到 `master`） |
| `path` | 否 | 仓库中 Skill 文件所在的子目录 — 支持单个仓库托管多个 Skills |
### 工作原理
1. **清单拉取** — CCSM 根据 Marketplace 仓库 URL 构建 raw 文件 URL，从 `main` 或 `master` 分支获取 `skills.json`。兼容 GitHub、Gitea、GitLab 以及任何提供 raw 文件端点的 Git 托管平台。
2. **Skill 下载** — 当用户安装 Skill 时，CCSM 从 Git 托管平台下载 Skill 仓库的归档文件（ZIP 或 tar.gz），解压后将文件部署到 `~/.claude/skills/<name>/`。
3. **Monorepo 支持** — 如果 Skill 条目指定了 `path`，CCSM 会在解压后进入该子目录再进行部署，从而支持单个仓库托管多个 Skills。
### Skill 仓库的内容
每个 Skill 仓库都是一个标准的 Claude Code Skill 目录。至少需要包含一个 `SKILL.md` 清单文件：
```
my-skill-repo/
SKILL.md # Claude Code Skill 清单
script.py # 辅助文件
templates/
template.txt
```
### 发布步骤
1. 创建一个**公开**的 Git 仓库，在根目录放置符合上述格式的 `skills.json`。
2. 推送上去。
3. 任何人都可以通过 `ccsm marketplace add <url>` 注册使用。
## 数据存储位置
| 路径 | 用途 |
|------|------|
| `~/.claude/skills/` | Claude Code 的 Skills 目录 —— Skills 的部署目标 |
| `~/.config/ccsm/config.json` | CCSM 配置文件（已注册的 Marketplace、默认模式） |
| `~/.config/ccsm/marketplaces/` | 缓存的 Marketplace 清单 |
| `~/.config/ccsm/skills/` | 下载的 Skill 文件（本地存储） |
在 Windows 上，`~/.config/` 对应 `C:\Users\<user>\AppData\Roaming\`。
## 许可证
Claude Code Skills Manager 是采用 MIT 许可证发布的开源软件。
docs/zh-hans/opensource-projects/delta-force-guide/api.md
+91
View File
@@ -0,0 +1,91 @@
---
title: Delta Force Guide API
---
## 后端 API 概览
后端是基于 Spring Boot 3 的应用程序，代码组织在基础包 `com.onixbyte.deltaforceguide` 下：
| 包 | 描述 |
|---|---|
| `controller` | REST API 端点控制器 |
| `service` | 业务逻辑层 |
| `repository` | MyBatis 数据访问层 |
| `domain` | JPA 实体与领域对象 |
| `config` | Spring 配置（安全、缓存等） |
| `properties` | 配置属性类 |
| `enumeration` | 枚举类型 |
| `shared` | 共享工具类 |
## API 端点
### 认证
| 方法 | 路径 | 描述 | 认证 |
|---|---|---|---|
| `POST` | `/api/auth/login` | 使用凭证登录 | 否 |
| `POST` | `/api/auth/refresh` | 刷新 access token | 否 |
| `GET` | `/api/auth/profile` | 获取当前用户信息 | 是 |
### 枪械
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/api/firearms` | 枪械列表（分页，可按类型筛选） |
| `GET` | `/api/firearms/:id` | 按 ID 获取枪械详情 |
| `POST` | `/api/firearms` | 创建新枪械 |
| `PUT` | `/api/firearms/:id` | 更新枪械信息 |
| `DELETE` | `/api/firearms/:id` | 删除枪械 |
### 改装
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/api/modifications` | 改装列表（分页，可按枪械和标签筛选） |
| `GET` | `/api/modifications/:id` | 按 ID 获取改装详情 |
| `POST` | `/api/modifications` | 创建改装 |
| `POST` | `/api/modifications/batch` | 批量创建改装 |
| `PUT` | `/api/modifications/:id` | 更新改装 |
| `DELETE` | `/api/modifications/:id` | 删除改装 |
| `DELETE` | `/api/modifications/batch-delete` | 批量删除改装 |
### 标签
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/api/tags` | 获取所有标签 |
## 前端路由
| 路径 | 布局 | 页面 | 描述 |
|---|---|---|---|
| `/` | 主布局 | 枪械浏览 | 首页 — 枪械列表 |
| `/firearms` | 主布局 | 枪械浏览 | 枪械详情与搜索 |
| `/mod-codes` | 主布局 | 改装代码 | 改装代码库 |
| `/legal` | 主布局 | 法律信息 | 法律与隐私信息 |
| `/login` | 空白布局 | 登录 | 用户认证页面 |
## 前端状态管理
Redux Toolkit 结合 Redux Persist 管理以下状态：
- **认证状态** — Access token、refresh token、用户信息
- **设置状态** — 用户偏好，持久化至本地存储
## API 客户端
前端使用基于 Axios 封装的共享 `WebClient`，提供以下能力：
- 基础 URL 配置（指向后端 API）
- 通过请求拦截器自动注入 JWT access token
- 在收到 401 响应时自动刷新 token
## 基础设施
| 组件 | 技术 |
|---|---|
| 数据库 | PostgreSQL（使用 Flyway 进行数据库迁移） |
| 缓存 | Redis（会话和 token 存储） |
| 文件存储 | AWS S3（枪械图片） |
| 容器化 | Docker |
| 部署 | Docker Compose + Nginx |
docs/zh-hans/opensource-projects/delta-force-guide/index.mdx
+48
View File
@@ -0,0 +1,48 @@
---
title: Delta Force Guide
---
import { Tabs, Tab } from "@rspress/core/theme"
## 介绍
Delta Force Guide 是一个全栈 Web 应用，为游戏 Delta Force（三角洲部队）提供可搜索的枪械改装代码库。项目包含两个组件：
- **Web 前端** — 基于 React 的单页应用，用于浏览、筛选和复制改装代码。
- **后端服务** — 基于 Spring Boot 的 REST API，处理数据持久化、身份认证和内容管理。
线上站点位于 **[dfguide.onixbyte.cn](https://dfguide.onixbyte.cn)**。
## 特性
- **枪械浏览** — 浏览精选的游戏内枪械列表及详细属性。
- **改装代码库** — 按武器、模式和标签搜索筛选改装代码。
- **一键复制** — 直接从界面复制改装代码。
- **高效渲染** — 通过窗口虚拟化实现大列表的流畅渲染。
- **身份认证** — 支持用户登录，采用 JWT 认证和验证码校验。
- **后台管理** — 枪械与改装数据完整的增删改查功能。
- **静态友好** — 前端以静态站点部署，通过 API 代理与后端通信。
## 架构
| 组件 | 技术栈 |
|---|---|
| **前端** | React 19、TypeScript、Tailwind CSS 4、Ant Design 6、React Router 7、Redux Toolkit、TanStack Virtual |
| **后端** | Spring Boot 3、Java 21、PostgreSQL、MyBatis、Flyway、Redis |
| **认证** | JWT（access 和 refresh token）、验证码集成 |
| **存储** | AWS S3（图片上传） |
前端是由 Vite 构建的静态站点，通过 API 与 Spring Boot 后端通信。认证采用 JWT access 和 refresh token 机制，refresh token 通过 Redis 管理。
## 代码仓库
- [delta-force-guide-server](https://github.com/onixbyte/delta-force-guide-server) — Spring Boot 后端
- [delta-force-guide-web](https://github.com/onixbyte/delta-force-guide-web) — React 前端
## 快速链接
- **线上站点：** [dfguide.onixbyte.cn](https://dfguide.onixbyte.cn)
## 许可证
Delta Force Guide 是采用 MIT 许可证发布的开源软件。
docs/zh-hans/opensource-projects/helix/index.mdx
+73
View File
@@ -0,0 +1,73 @@
---
title: Helix
---
## 介绍
Helix 是一个全栈企业级应用模板，旨在加速生产级业务应用的开发。它提供了预构建的基础，包含企业应用所需的全部基本功能，使团队能够专注于业务逻辑而非基础设施。
项目由两个组件构成：
- **Helix Server** — 基于 Spring Boot 的后端，提供 REST API、身份认证、权限管理和数据管理。
- **Helix Web** — 基于 React 的单页应用前端，具备现代化的 UI、基于角色的路由和企业级身份集成。
Helix 旨在作为项目的起点使用。Fork 或克隆它，然后在现成的基础上开始构建您自己的业务功能。
## 特性
### 后端（Helix Server）
- **身份认证与授权** — 基于 JWT 的 access token 和 refresh token 流程，配合 Spring Security。支持 Microsoft Entra ID（Azure AD）集成。
- **基于角色的访问控制** — 通过角色、权限和菜单级访问控制实现细粒度权限管理。
- **用户与组织管理** — 用户、部门、职位和角色的完整增删改查。
- **菜单管理** — 层级菜单树，支持按角色配置可见性。
- **资产管理** — 文件上传至 AWS S3，支持 CDN 前缀处理。
- **设置管理** — 类型化的应用配置项持久化至数据库。
- **验证码集成** — 登录和注册流程中的图形验证码校验。
- **Redis 缓存** — 高性能缓存，支持可配置 TTL 和自定义序列化器。
- **数据访问** — Spring Data JPA 与 MyBatis 混合持久化方案。
- **校验** — Bean Validation 分组校验与自定义校验约束。
### 前端（Helix Web）
- **企业级身份认证** — 通过 MSAL 实现 Microsoft Entra ID 登录。可扩展的社交登录提供商架构（Microsoft、Google、GitLab、Slack、Discord、钉钉、飞书、企业微信、邮箱/密码）。
- **仪表盘布局** — 响应式管理后台，可折叠侧边栏，基于角色的菜单渲染。
- **用户管理** — 数据表格支持搜索、分页，添加/编辑对话框，角色分配和手机号校验。
- **角色与菜单管理** — 角色增删改查与权限分配。基于树形的菜单配置。
- **部门与职位** — 组织层级管理界面。
- **路由保护** — 在页面加载前检查认证和授权状态。
- **状态管理** — Redux Toolkit 配合 Redux Persist 实现认证 token 的持久化。
- **HTTP 客户端** — 基于 Axios 封装的请求客户端，自动注入 JWT token 并在 401 时自动刷新。
## 架构
| 层 | 技术栈 |
| ---------- | ---------------------------------------------------------------------------------------------- |
| **前端** | React 19、TypeScript、Tailwind CSS 4、Ant Design 6、React Router 7、Redux Toolkit、Axios、MSAL |
| **后端** | Spring Boot 3.5、Java 21、Spring Security、MyBatis、Spring Data JPA |
| **数据库** | PostgreSQL（使用 Flyway 迁移） |
| **缓存** | Redis（会话和 token 存储） |
| **存储** | AWS S3（资源上传） |
前端通过 RESTful JSON API 与后端通信。认证流程使用短有效期的 JWT access token，refresh token 存储在 Redis 中。Microsoft Entra ID 集成在前端通过 MSAL 处理，并在后端进行校验。
## 代码仓库
Helix 采用单仓库（monorepo）结构，前后端都在同一个仓库中。
- [server/](https://github.com/onixbyte-opensource/helix/tree/main/server) — Spring Boot 后端
- [web/](https://github.com/onixbyte-opensource/helix/tree/main/web) — React 前端
## 快速开始
Helix 是一个模板项目。启动新项目的步骤：
1. Fork 或克隆 [Helix 仓库](https://github.com/onixbyte-opensource/helix)。
2. 在后端配置您的数据库、Redis 和 S3 设置。
3. 在前端配置您的认证提供商和 API 基础地址。
4. 启动后端：`./gradlew bootRun`
5. 启动前端：`pnpm install && pnpm dev`
## 许可证
Helix 是采用 MIT 许可证发布的开源软件。
docs/zh-hans/opensource-projects/index.md
+25
View File
@@ -0,0 +1,25 @@
---
title: 开源生态
---
由 OnixByte 开发的开源项目。
## 库和工具包
- **[OnixByte Toolbox](/opensource-projects/onixbyte-toolbox)** — 面向 Java 应用的开发工具包：AES、哈希、Base64、集合工具、密钥加载器、统计计算器、标识符生成器和泛型元组。
- **[regions4j](/opensource-projects/regions4j)** — 基于 ISO 3166-1 的类型安全 Java 枚举地区元数据，支持 O(1) 查找、E.164 拨号前缀和区域标签。
- **[Captcha](/opensource-projects/captcha)** — 现代化的 Java 验证码生成库，支持水波纹、鱼眼和阴影扭曲效果。
- **[Calendar Toolbox](/opensource-projects/calendar-toolbox)** — 遵循 iCalendar 规范（RFC 5545）创建 `.ics` 文件的 Java 库。
## 全栈应用
- **[Helix](/opensource-projects/helix)** — 企业级应用模板，后端使用 Spring Boot，前端使用 React，集成 JWT 认证、RBAC 权限管理、用户与组织管理以及 Microsoft Entra ID 集成。
- **[Delta Force Guide](/opensource-projects/delta-force-guide)** — 为游戏《三角洲行动》提供可搜索枪械改装代码库的 Web 应用，包含 React 单页应用和 Spring Boot REST API。
## 开发者工具
- **[Claude Code Skills Manager](/opensource-projects/claude-code-skill-manager)** — 用于从基于 Git 的 Marketplace 仓库中发现、安装和管理 Claude Code Skills 的 CLI 工具。
## Vite 插件
- **[Port Checker](/opensource-projects/vite-plugins/port-checker)** — 当 Vite 开发服务器监听浏览器限制的端口时发出警告，避免无响应的连接失败。
docs/zh-hans/opensource-projects/onixbyte-toolbox/api.md
+209
View File
@@ -0,0 +1,209 @@
---
title: OnixByte Toolbox API
---
## 包结构概览
所有模块均在 `com.onixbyte` group ID 下发布。每个模块有自己独立的基础包：
| 模块 | Maven Artifact | 基础包 |
|---|---|---|
| Common Toolbox | `common-toolbox` | `com.onixbyte.common` |
| Crypto Toolbox | `crypto-toolbox` | `com.onixbyte.crypto` |
| Math Toolbox | `math-toolbox` | `com.onixbyte.math` |
| Tuple | `tuple` | `com.onixbyte.tuple` |
| Identity Generator | `identity-generator` | `com.onixbyte.identitygenerator` |
---
## Common Toolbox
### 适配器
`ObjectMapAdapter` — 对象与 Map 之间的转换器。适用于需要键值表示的场景，如序列化或数据转换。
```java
import com.onixbyte.common.adapter.ObjectMapAdapter;
```
### 工具类
| 类 | 描述 |
|---|---|
| `AesUtil` | AES 对称加密/解密，支持密钥生成 |
| `Base64Util` | Base64 编解码，支持多种字符集 |
| `BoolUtil` | 布尔值解析与转换工具 |
| `BranchUtil` | 条件分支辅助，支持函数式链式调用 |
| `CollectionUtil` | 集合操作 — 分组、分区、合并 |
| `HashUtil` | 哈希工具，支持 MD5、SHA-1、SHA-256、SHA-512 |
| `MapUtil` | Map 构建、合并和转换辅助 |
| `RangeUtil` | 数值范围操作，支持边界处理 |
**AesUtil 示例：**
```java
var key = AesUtil.generateKey();
var encrypted = AesUtil.encrypt("hello world", key);
var decrypted = AesUtil.decrypt(encrypted, key);
```
**HashUtil 示例：**
```java
var md5 = HashUtil.md5("hello world");
var sha256 = HashUtil.sha256("hello world");
var fileSha = HashUtil.sha256(new File("data.bin"));
```
**CollectionUtil 示例：**
```java
var partitioned = CollectionUtil.partition(list, 100);
var grouped = CollectionUtil.groupBy(users, User::getDepartment);
```
---
## Crypto Toolbox
提供了加载 PEM 格式密钥的简洁抽象。支持 RSA 和 ECDSA 算法。
### 密钥加载器
| 类 | 描述 |
|---|---|
| `RSAPrivateKeyLoader` | 从 PEM 字符串加载 RSA 私钥 |
| `RSAPublicKeyLoader` | 从 PEM 字符串加载 RSA 公钥 |
| `ECPrivateKeyLoader` | 从 PEM 字符串加载 ECDSA 私钥 |
| `ECPublicKeyLoader` | 从 PEM 字符串加载 ECDSA 公钥 |
所有密钥加载器实现 `PrivateKeyLoader` 或 `PublicKeyLoader` 接口。
**RSA 示例：**
```java
var privateKey = new RSAPrivateKeyLoader().load(pemString);
var publicKey = new RSAPublicKeyLoader().load(pemString);
```
**ECDSA 示例：**
```java
var ecPrivateKey = new ECPrivateKeyLoader().load(pemString);
var ecPublicKey = new ECPublicKeyLoader().load(pemString);
```
### 工具类
`CryptoUtil` — 提供便捷的数字签名生成和验证方法，以及通用密码学辅助功能。
### 异常
| 类 | 描述 |
|---|---|
| `KeyLoadingException` | PEM 格式密钥解析失败时抛出 |
---
## Math Toolbox
用于处理数值数据集的统计计算工具。
### 核心类
| 类 | 描述 |
|---|---|
| `Calculator` | 统计计算器 — 均值、中位数、方差、标准差、总和、最小值、最大值 |
| `PercentileCalculator` | 百分位数计算器，支持可配置的插值策略 |
**Calculator 示例：**
```java
var stats = new Calculator(Arrays.asList(1.0, 2.0, 3.0, 4.0, 5.0));
double mean = stats.getMean();
double median = stats.getMedian();
double stdDev = stats.getStandardDeviation();
```
**PercentileCalculator 示例：**
```java
var calculator = new PercentileCalculator(data);
double p95 = calculator.calculate(95);
double p99 = calculator.calculate(99);
```
### 数据模型
| 类 | 描述 |
|---|---|
| `QuartileBounds` | 包含 Q1、中位数（Q2）、Q3 值及 IQR 和须线边界 |
---
## Tuple
轻量级泛型元组类型，适用于需要返回多个值但无需定义专用类的场景。
### 类
| 类 | 类型参数 | 可变性 |
|---|---|---|
| `Tuple<A, B>` | 两个元素 | 可变 |
| `ImmutableTuple<A, B>` | 两个元素 | 不可变 |
| `Triple<A, B, C>` | 三个元素 | 可变 |
| `ImmutableTriple<A, B, C>` | 三个元素 | 不可变 |
**示例：**
```java
var pair = Tuple.of("key", 42);
var triple = Triple.of("id", "name", 100);
var immutable = ImmutableTuple.of("constant", true);
// 访问器
String first = pair.getFirst();
Integer second = pair.getSecond();
// 三元组访问器
String a = triple.getFirst();
String b = triple.getSecond();
Integer c = triple.getThird();
```
---
## Identity Generator
生成适用于数据库主键或分布式 ID 的唯一标识符。
### 接口
`IdentityGenerator<T>` — 生成类型为 `T` 的标识符。
### 实现
| 类 | 描述 |
|---|---|
| `SequentialUuidGenerator` | 生成时间排序的顺序 UUID（优化数据库索引性能） |
| `SnowflakeIdentityGenerator` | 雪花算法分布式唯一 ID 生成 |
**顺序 UUID：**
```java
var generator = new SequentialUuidGenerator();
UUID id = generator.nextId(); // 时间排序 UUID，对 B-tree 友好
```
**雪花：**
```java
var generator = new SnowflakeIdentityGenerator(workerId, datacenterId);
long id = generator.nextId(); // 64 位雪花 ID
```
### 异常
| 类 | 描述 |
|---|---|
| `TimingException` | 系统时钟回拨时抛出，保证 ID 唯一性不受影响 |
docs/zh-hans/opensource-projects/onixbyte-toolbox/index.mdx
+54
View File
@@ -0,0 +1,54 @@
---
title: OnixByte Toolbox
---
import { Tabs, Tab } from "@rspress/core/theme"
## 介绍
OnixByte Toolbox 是一个面向 Java 应用的开发工具包，提供了一系列便捷、可复用的工具，帮助开发者高效编写代码。它由 OnixByte 设计和维护，采用 monorepo 架构，包含多个专用库，每个库解决一个特定的开发需求 — 从通用工具类和密码学，到数学计算和标识符生成。
该工具包已发布到 Maven Central，使用 `com.onixbyte` 作为 group ID。每个模块独立版本管理，可在任何 Java 17+ 项目中使用。
## 模块
| 模块 | Artifact ID | 描述 |
|--------------------|----------------------|-----------------------------------|
| Common Toolbox | `common-toolbox` | 日常工具类 — AES 加密、哈希、Base64、集合、分支、范围 |
| Crypto Toolbox | `crypto-toolbox` | RSA 和 ECDSA 算法的公私钥加载 |
| Math Toolbox | `math-toolbox` | 统计计算、百分位数分析、四分位数计算 |
| Tuple | `tuple` | 泛型二元组和三元组，含不可变版本 |
| Identity Generator | `identity-generator` | 雪花算法和顺序 UUID 唯一标识符生成 |
| Version Catalogue | `version-catalogue` | OnixByte 项目的集中式 Gradle 版本目录 |
## 安装
在构建配置中添加所需模块的依赖：
<Tabs>
<Tab label="Gradle with Kotlin DSL">
```kotlin title="build.gradle.kts"
dependencies {
implementation("com.onixbyte:$artefactId:$version")
}
```
</Tab>
<Tab label="Maven">
```xml title="pom.xml"
<dependency>
<groupId>com.onixbyte</groupId>
<artifactId>${artefactId}</artifactId>
<version>${version}</version>
</dependency>
```
</Tab>
</Tabs>
## 要求
- Java 17 或更高版本
## 许可证
OnixByte Toolbox 是采用 MIT 许可证发布的开源软件。
docs/zh-hans/opensource-projects/regions4j/index.mdx
+104
View File
@@ -0,0 +1,104 @@
---
title: Regions for Java
---
import { Tabs, Tab } from "@rspress/core/theme"
## 介绍
**regions4j** 是一个轻量级、类型安全的 Java 库，基于 ISO 3166-1 标准提供全面的世界地区元数据。它旨在简化 Java 企业应用中的国际化（i18n）、电信路由和地区数据管理工作。
该库将每个 ISO 3166-1 国家和地区建模为枚举常量，使您在引用地区时获得编译期安全性和 IDE 自动补全支持。凭借内置的 O(1) 查找、零外部依赖和 Java 8 兼容性，它适用于任何规模的项目 — 从微服务到整体式企业系统。
## 特性
- **ISO 3166-1 合规** — 完整支持所有已分配国家和地区的 Alpha-2（`abbreviation`）和 Alpha-3（`code`）格式。
- **电信元数据** — 包含每个地区的 E.164 国际拨号前缀。
- **区域支持** — 每个地区提供默认的区域标签（如 `zh_HK`、`en_US`、`en_GB` 等），辅助 i18n 工作流。
- **高性能** — 线程安全、不可变的内部哈希映射提供常量时间的缩写或代码查找。
- **零依赖** — 纯 Java 库，无任何外部依赖。
- **日历化版本管理** — 版本号采用 `YYYY.MM` 格式（如 `2025.12`），以透明地反映底层 ISO 数据的新鲜度，而非语义化版本号。
## 核心数据模型
每个地区暴露四个属性：
| 属性 | 类型 | 描述 | 示例 |
|---|---|---|---|
| `abbreviation` | String | ISO 3166-1 alpha-2 缩写 | `HK`、`US`、`GB`、`RU` |
| `code` | String | ISO 3166-1 alpha-3 代码 | `HKG`、`USA`、`GBR`、`RUS` |
| `callingCode` | String | E.164 国际拨号前缀 | `852`、`1`、`44`、`7` |
| `locale` | String | 默认语言和地区标签 | `zh_HK`、`en_US`、`en_GB`、`ru_RU` |
## 安装
<Tabs>
<Tab label="Gradle with Kotlin DSL">
```kotlin title="build.gradle.kts"
dependencies {
implementation("com.onixbyte:regions4j:$version")
}
```
</Tab>
<Tab label="Maven">
```xml title="pom.xml"
<dependency>
<groupId>com.onixbyte</groupId>
<artifactId>regions4j</artifactId>
<version>${version}</version>
</dependency>
```
</Tab>
</Tabs>
> **版本说明：** 该库使用日历化版本管理（`YYYY.MM`）而非语义化版本号。版本字符串如 `2025.12` 可以直观地告诉您地区数据反映的是 2025 年 12 月的 ISO 3166-1 状态。
## 使用
### 直接访问
通过枚举常量直接引用任何地区：
```java
Region uk = Region.UNITED_KINGDOM;
uk.getAbbreviation(); // "GB"
uk.getCode(); // "GBR"
uk.getDialCode(); // "44"
uk.getLocale(); // "en_GB"
```
### 高效查找
从字符串输入中查找地区 — 非常适合处理 Web 请求、API 负载或数据库记录：
```java
// 按 Alpha-2 缩写查找（区分大小写）
Region region = Region.fromAbbreviation("HK");
// 按 Alpha-3 代码查找（不区分大小写）
Region region = Region.fromCode("HKG");
```
### Java Locale 集成
将地区的 locale 字符串转换为 `java.util.Locale` 以配合标准 Java i18n API 使用：
```java
Region region = Region.CHINA;
Locale javaLocale = Locale.forLanguageTag(region.getLocale().replace("_", "-"));
javaLocale.getDisplayCountry(Locale.UK); // "China"
```
## 性能
首次访问时，库会将所有地区初始化到不可变的 `HashMap` 结构中。后续通过 `fromAbbreviation()` 和 `fromCode()` 进行的查找均为线程安全且以常量时间运行 — 适用于高吞吐量的请求路径。
## 要求
- Java 8 或更高版本
## 许可证
regions4j 是采用 MIT 许可证发布的开源软件。
docs/zh-hans/opensource-projects/vite-plugins/index.mdx
+11
View File
@@ -0,0 +1,11 @@
---
title: Vite 插件
---
## 概览
由 OnixByte 开发和维护的 Vite 插件合集。每个插件旨在解决 Vite 开发工作流中的特定问题 — 轻量级、零依赖、即插即用。
## 可用插件
- **[Port Checker](/opensource-projects/vite-plugins/port-checker)** — 当开发服务器监听浏览器限制的端口（依据 Fetch 规范）时发出警告，帮助您避免无响应的连接失败。
docs/zh-hans/opensource-projects/vite-plugins/port-checker/index.mdx
+67
View File
@@ -0,0 +1,67 @@
---
title: Port Checker
---
import { Tabs, Tab } from "@rspress/core/theme"
## 介绍
**vite-plugin-port-checker** 是一个轻量级的 Vite 插件，可在开发服务器监听被常见浏览器屏蔽的端口时发出警告。Chrome 和 Firefox 等浏览器维护了一份[受限制端口列表](https://fetch.spec.whatwg.org/#port-blocking) — 这些端口通常与 SMTP、SSH 和 DNS 等知名协议关联 — 并拒绝连接这些端口。如果不小心将开发服务器运行在这些端口上，会导致令人困惑的"连接被拒绝"或"已被屏蔽"错误，且没有任何明确的解释。
该插件会在启动时检测到这种情况，并向控制台打印一条清晰且带有颜色标记的警告，建议您修改 Vite 配置中的 `server.port` 设置。
## 特性
- **自动检测** — 对照完整的 Fetch 规范端口屏蔽列表（68 个受限端口）检查开发服务器端口。
- **清晰的警告** — 黄色高亮控制台输出，并提供可操作的指导。
- **零配置** — 开箱即用，无需设置任何选项。
- **轻量级** — 单文件插件，除 Vite 本身外无任何依赖。
## 安装
<Tabs>
<Tab label="npm">
```bash
npm install vite-plugin-port-checker -D
```
</Tab>
<Tab label="pnpm">
```bash
pnpm add vite-plugin-port-checker -D
```
</Tab>
</Tabs>
## 使用
在 `vite.config.ts` 中添加插件：
```ts title="vite.config.ts"
import { defineConfig } from "vite"
import checkRestrictedPort from "vite-plugin-port-checker"
export default defineConfig({
plugins: [checkRestrictedPort()],
})
```
当开发服务器启动在受限端口（如 25、22 或 53 端口）时，您将看到：
```
[Warning] The current listening port 25 is categorised as a restricted port
by most browsers. This may prevent you from accessing the application.
Please consider changing the port in your 'vite.config.ts' or 'vite.config.js'
via 'server.port'.
```
## 工作原理
该插件通过钩入 Vite 的 `configureServer` 生命周期工作。当 HTTP 服务器触发 `listening` 事件后，插件检查绑定的端口号，并与 [Fetch 规范](https://fetch.spec.whatwg.org/#port-blocking)中定义的 68 个受限端口进行比对。如果匹配，则通过黄色的 `console.warn` 消息提醒开发者。
## 要求
- Vite 3.0.0 或更高版本
## 许可证
vite-plugin-port-checker 是采用 MIT 许可证发布的开源软件。