Immutable. This exact content is served forever at /api/v1/blob/b36b65fb6f9753de.
---
name: cosid-spring-boot
description: Configure CosId in Spring Boot applications with cosid-spring-boot-starter. Use when the user works with application.yml, Gradle or Maven dependencies, starter feature variants, Redis/JDBC/MongoDB/ZooKeeper/proxy distributors, SnowflakeId, SegmentId, SegmentChainId, CosIdGenerator, @CosId, IdGeneratorProvider, ID converters, machine guarder settings, clock-backwards synchronization, or Actuator endpoints in a Spring Boot service.
---
# CosId Spring Boot Integration
CosId is a universal, flexible, high-performance distributed ID generator for Java 17+. The Spring Boot starter (`cosid-spring-boot-starter`) provides auto-configuration for all ID generation strategies.
## Workflow
1. Confirm the user's Spring Boot and CosId major versions. CosId 2.x targets Spring Boot 3.x and Java 17; CosId 3.x targets Spring Boot 4.x and Java 17.
2. Choose the ID strategy. Use `$cosid-strategy-guide` first when the user has not chosen between SnowflakeId, SegmentId, SegmentChainId, and CosIdGenerator.
3. Select the distributor and starter capability needed by the deployment: Redis, JDBC, MongoDB, ZooKeeper, proxy, manual, or StatefulSet.
4. Provide the smallest working YAML for the selected strategy and backend.
5. Show how the application consumes the generator: shared bean, named provider, or `@CosId`.
6. Add validation guidance for uniqueness, ordering, machine ID ownership, segment allocation, and Actuator visibility.
## Dependency Setup
Add the BOM and starter to your Gradle build. When you need a distributor backend, select the corresponding Gradle feature capability:
```groovy
dependencies {
implementation platform("me.ahoo.cosid:cosid-bom:${cosidVersion}")
// Redis backend. Replace the capability with jdbc-support, mongo-support,
// zookeeper-support, proxy-support, actuator-support, etc. as needed.
implementation("me.ahoo.cosid:cosid-spring-boot-starter") {
capabilities {
requireCapability("me.ahoo.cosid:spring-redis-support")
}
}
}
```
For Maven, import the BOM and add the starter plus the backend module explicitly:
```xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>me.ahoo.cosid</groupId>
<artifactId>cosid-bom</artifactId>
<version>${cosid.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>me.ahoo.cosid</groupId>
<artifactId>cosid-spring-boot-starter</artifactId>
</dependency>
<!-- Redis backend. Use cosid-jdbc, cosid-mongo, or cosid-zookeeper for other backends. -->
<dependency>
<groupId>me.ahoo.cosid</groupId>
<artifactId>cosid-spring-redis</artifactId>
</dependency>
</dependencies>
```
## Choosing an ID Strategy
There are 4 ID generation strategies in CosId. The right choice depends on your requirements:
| Strategy | Throughput | Trend | Best For |
|---|---|---|---|
| **CosIdGenerator** | ~15M+/s | Time-ordered | Standalone apps, no distributed coordination needed |
| **SnowflakeId** | ~4M+/s | Time-ordered | Distributed systems needing sortable IDs, typical microservices |
| **SegmentId** | ~20M+/s | Monotonic | High-throughput with simple coordination, trend-increasing |
| **SegmentChainId** | ~127M+/s | Monotonic | Maximum throughput, lock-free prefetching, production workloads |
### Decision Guide
- **Need maximum performance and have Redis/JDBC available?** → SegmentChainId (default segment mode)
- **Need time-sortable IDs across machines?** → SnowflakeId
- **Need compact string IDs or a large machine-ID design space?** → CosIdGenerator
- **Database-friendly monotonic IDs?** → SegmentId or SegmentChainId
- **Need only strategy selection?** → Use `$cosid-strategy-guide` before writing YAML
## Configuration Templates
### Full-featured Redis Setup (Most Common)
This is the most typical production configuration with both SnowflakeId and SegmentChainId:
```yaml
cosid:
namespace: ${spring.application.name}
machine:
enabled: true
distributor:
type: redis
generator:
enabled: true
snowflake:
enabled: true
share:
enabled: true # shared SnowflakeId as default IdGenerator
provider:
order_id:
converter:
type: radix
prefix: ORDER
radix:
char-size: 11
pad-start: true
segment:
enabled: true
mode: chain # CHAIN = SegmentChainId (recommended), SEGMENT = basic SegmentId
distributor:
type: redis
share:
enabled: true # shared SegmentChainId as default StringIdGenerator
provider:
user_id:
step: 100
converter:
type: to_string
to-string:
char-size: 10
pad-start: true
```
### JDBC Backend Setup
For environments where only a relational database is available:
```yaml
cosid:
namespace: ${spring.application.name}
machine:
enabled: true
distributor:
type: jdbc
jdbc:
enable-auto-init-cosid-machine-table: true # auto-create cosid_machine (default false)
segment:
enabled: true
mode: chain
distributor:
type: jdbc
jdbc:
enable-auto-init-cosid-table: true
enable-auto-init-id-segment: true
```
This auto-creates the `cosid`/`cosid_machine` tables and segment rows. Note: if you register your own `JdbcMachineIdInitializer` bean, the machine-table auto-init flag is silently bypassed (`@ConditionalOnMissingBean` back-off) — perform the DDL yourself in that case. The segment table schema:
```sql
CREATE TABLE IF NOT EXISTS cosid (
name VARCHAR(100) NOT NULL,
last_max_id BIGINT NOT NULL DEFAULT 0,
last_fetch_time BIGINT NOT NULL DEFAULT 0,
PRIMARY KEY (name)
);
```
### MongoDB Backend Setup
```yaml
cosid:
namespace: ${spring.application.name}
machine:
enabled: true
distributor:
type: mongo
mongo:
database: cosid_db
segment:
enabled: true
mode: chain
distributor:
type: mongo
mongo:
database: cosid_db
```
### ZooKeeper Backend Setup
```yaml
cosid:
namespace: ${spring.application.name}
machine:
enabled: true
distributor:
type: zookeeper
snowflake:
enabled: true
segment:
enabled: true
mode: chain
distributor:
type: zookeeper
```
### Manual Machine ID (for fixed-instance deployments)
When you have a known, fixed set of instances:
```yaml
cosid:
namespace: ${spring.application.name}
machine:
enabled: true
distributor:
type: manual
manual:
machine-id: 1 # must be unique per instance
snowflake:
enabled: true
```
### Kubernetes StatefulSet
For StatefulSet deployments, the pod ordinal is used as the machine ID:
```yaml
cosid:
namespace: ${spring.application.name}
machine:
enabled: true
distributor:
type: stateful_set
snowflake:
enabled: true
```
## ID Converter Types
Converters transform `long` IDs into `String` representations. Configure via `converter` in each provider definition.
| Type | Description | Example Output |
|---|---|---|
| `radix` (default) | Base62 encoding (0-9, A-Z, a-z) | `ORDER-0Gjk3R0p` |
| `radix36` | Base36 encoding (0-9, A-Z) | `BIZ-00001234` |
| `to_string` | Plain decimal string with padding | `0000000001` |
| `snowflake_friendly` | Human-readable snowflake timestamp | `20240101-120000-1-0-0` |
| `custom` | Your own `IdConverter` implementation | — |
### Converter Configuration Examples
```yaml
# Short alphanumeric ID (radix62)
converter:
type: radix
prefix: ORDER
radix:
char-size: 11
pad-start: true
# Numeric string with date prefix
converter:
type: to_string
prefix: BIZ-
date-prefix:
enabled: true
pattern: yyMMdd
to-string:
char-size: 10
pad-start: true
# Human-readable snowflake
converter:
type: snowflake_friendly
friendly:
pad-start: true
# With group-based prefix (for date-partitioned segments)
converter:
type: to_string
prefix: BIZ-
group-prefix:
enabled: true
to-string:
char-size: 8
pad-start: true
```
## Using the ID Generator in Code
### Injecting the Shared IdGenerator
When `share.enabled: true`, a default `IdGenerator` bean is registered:
```java
@Service
public class OrderService {
private final IdGenerator idGenerator;
public OrderService(IdGenerator idGenerator) {
this.idGenerator = idGenerator;
}
public Order createOrder() {
long orderId = idGenerator.generate();
String orderIdStr = idGenerator.generateAsString();
// ...
}
}
```
### Injecting Named Generators
Named generators from `provider` are available via `IdGeneratorProvider`:
```java
@Service
public class UserService {
private final IdGenerator userIdGenerator;
public UserService(IdGeneratorProvider provider) {
this.userIdGenerator = provider.get("user_id");
}
public User createUser() {
long userId = userIdGenerator.generate();
// ...
}
}
```
### Using @CosId Annotation
The `@CosId` annotation auto-assigns IDs to entity fields:
```java
import me.ahoo.cosid.annotation.CosId;
public class Order {
@CosId("order_id")
private Long id;
// getters/setters
}
```
### SnowflakeId State Parsing
Parse snowflake IDs back into their components via the state parser (the `SnowflakeId` interface has no `getStateParser()` — build one from the generator):
```java
import me.ahoo.cosid.snowflake.SnowflakeIdStateParser;
SnowflakeIdStateParser parser = SnowflakeIdStateParser.of(snowflakeId);
SnowflakeIdState state = parser.parse(id);
// state.getTimestamp(), state.getMachineId(), state.getSequence()
```
## SnowflakeId Bit Layout Customization
The default MillisecondSnowflakeId uses 41-bit timestamp, 10-bit machineId, 12-bit sequence. Customize per-provider:
```yaml
cosid:
snowflake:
provider:
short_lived_id:
timestamp-unit: second # use seconds instead of milliseconds
epoch: 1577203200 # default COSID_EPOCH in seconds (2019-12-24 16:00 UTC)
timestamp-bit: 31
machine-bit: 10
sequence-bit: 22
```
Bit allocation must satisfy: `timestampBit + machineBit + sequenceBit = 63`.
## Segment Grouping (Date-partitioned IDs)
Group segments by time period for date-based ID sequences:
```yaml
cosid:
segment:
provider:
daily_order:
group:
by: year_month_day # or year, year_month
pattern: yyMMdd
converter:
type: to_string
prefix: BIZ-
group-prefix:
enabled: true
to-string:
char-size: 8
pad-start: true
```
## Machine ID Management
### Guarder Configuration
The guarder keeps machine ID registrations alive via heartbeat:
```yaml
cosid:
machine:
enabled: true
distributor:
type: redis
guarder:
enabled: true
safe-guard-duration: 5m # how long the guard is valid
initial-delay: 1s
delay: 10s
```
### Clock Backwards Synchronization
Handle clock drift in distributed environments:
```yaml
cosid:
machine:
enabled: true
clock-backwards:
spin-threshold: 100
broken-threshold: 2000
```
- `spin-threshold`: Small clock drift is handled by spinning/waiting
- `broken-threshold`: Large clock drift throws `ClockTooManyBackwardsException`
### State Storage
Machine state persists locally to survive restarts:
```yaml
cosid:
machine:
enabled: true
state-storage:
local:
state-location: .cosid-machine-state # default path
```
## Proxy Mode
For architectures that prefer a dedicated ID service (cosid-proxy-server). There is no `cosid.proxy.enabled` switch — the proxy backend activates through the `proxy-support` starter capability plus `distributor.type: proxy`:
```yaml
# Client side
cosid:
proxy:
host: http://cosid-proxy:8688 # ProxyProperties only has `host`
segment:
enabled: true
mode: chain
distributor:
type: proxy
```
Since 3.2.1 a proxy-server restart self-heals: `nextMaxId` rebuilds the in-memory distributor cache lazily from the backing store, so already-running clients recover without a restart.
## Actuator / Monitoring
Enable Spring Boot Actuator endpoints for monitoring:
```yaml
management:
endpoints:
web:
exposure:
include:
- cosid
- cosidGenerator
- cosidStringGenerator
- health
endpoint:
health:
show-details: always
```
The `cosid` endpoint shows all registered ID generators and their stats.
## Validation Checklist
- Run a focused Spring Boot test that loads the application context with the chosen backend capability.
- Generate IDs concurrently and assert uniqueness.
- For SnowflakeId, verify machine ID allocation and clock-backwards settings.
- For SegmentId/SegmentChainId, verify the segment distributor initializes the `cosid` table or backend state.
- For converters, assert the expected prefix, padding, radix, and string length.
- For shared beans, assert `IdGenerator` or `StringIdGenerator` resolves to the intended provider.
- For production services, expose and inspect the CosId Actuator endpoint when actuator support is enabled.
## Response Template
When answering a Spring Boot integration request, include:
1. Dependency coordinates and the required backend capability.
2. Minimal `application.yml` for the selected generator.
3. Code snippet for injection or `@CosId`.
4. Operational notes for machine ID, clock, state storage, and monitoring.
5. A small test or verification command the user can run.