common-random fills a database with plausible Chinese names, addresses and card numbers

The value is data that passes the format checks, not data that is random

The project describes itself as an easy to use random data generator, generally used for data filling, simulation, demonstration and other scenarios in the development and test phase, and it can be integrated into any type of Java project. The distinguishing claim is that the generated random data is relatively close to real data, and the feature list is where that becomes concrete. It generates Chinese and English personal names, Chinese national ID card numbers that follow the checksum rule, mainland China mobile phone numbers, QQ numbers, ethnic group names, education records from primary school through university with names, grades and classes, and financial records including stock names with codes, daily K-line data, open ended fund names, currency information and virtual bank card numbers. The list continues into sports teams from the major football leagues, and into a miscellaneous category that includes licence plate numbers, ISBNs, EAN codes, industry classifications, the unified social credit code, and company and department names. That is the point of the library. A placeholder string breaks a validation rule or a database constraint, and this one is built so that it does not.

Everything hangs off a single RandomSource entry point

The API is organised by domain, and the entry point is a single static class with one factory method per category. The areas cover the region, date and time, education, financial, internet, number, personal information, sport, language and text, and miscellaneous data, each returning its own source object. The generators are then called on those source objects, and the naming is consistent, so a random Chinese name comes from the person information source and a random email address comes from the internet source. Two design choices are worth noting. First, the sources are obtained fresh on each call in the examples, so a caller that wants many values of the same kind re-resolves the source each time, which is a style detail rather than a performance issue at test data volumes. Second, the method names carry the type in the argument, so a call that generates a random integer takes the lower and upper bounds, and the array variants take a count as the last argument, which makes bulk generation a one line change from the single value case.

The dependency coordinates changed in 1.1, and the old ones still resolve

The install instructions are the part with a real trap in them, and the README flags it. The latest 1.1.x version has been published to the central repository, with the note that the groupId has changed. The current coordinates are:

<dependency>
    <groupId>io.github.yindz</groupId>
    <artifactId>common-random</artifactId>
    <version>1.1.0</version>
</dependency>

The older 1.0.x line is still published under the previous group:

<dependency>
    <groupId>com.apifan.random</groupId>
    <artifactId>common-random</artifactId>
    <version>1.0.21</version>
</dependency>

So the same artifactId exists under two groupIds, and a project that upgrades the coordinates but keeps the old version, or that ends up with both on the classpath through different transitive paths, will have two copies of the library with the same packages on the classpath. The Java version requirement is 1.8 or higher, and the badge in the README shows the same, which is worth noting for a project still on that baseline.

Generated ID card numbers pass the checksum but can collide with real ones

The ID card generator is the most interesting piece because it encodes a rule rather than a format. The API takes a province, a date range or an age, and a gender, and it produces a number that satisfies the official checksum. The region code data comes from the Ministry of Civil Affairs 2019 public data, which the README links. The documentation carries a warning that matters for how you use it: a randomly generated virtual ID number follows the validation rules, but it is possible for it to coincide with a real number purely by chance. That is a small probability per value and a real one across a large seed set, so a database seeded with tens of thousands of records has a non-trivial chance of containing a number that belongs to someone. The same caution applies to the bank card generator, and the README is explicit there, saying the random virtual bank card numbers only have a prefix and length that follow the rules, will not overlap with real card numbers, cannot be used for payment, and are for simulation, testing and demonstration only.

The internet and personal generators cover the fields a schema usually demands

The internet source produces virtual email addresses with a configurable maximum username length and an optional fixed domain suffix, virtual domain names with a maximum length, static URLs, public and private IPv4 addresses, IPv6 addresses, network interface MAC addresses, strong passwords, user agent strings, port numbers, and application names with bundle identifiers and version numbers. The personal source covers Chinese and English names in male, female and random variants, network nicknames including a pinyin transliterated form, Chinese mainland mobile numbers, QQ numbers and non mainstream QQ nicknames, and ethnic group names. The geographic source adds provinces and cities, countries and regions based on the ISO 3166-1 standard, virtual longitude and latitude, postcodes, contact addresses, and landline area codes and numbers. The date and time source covers random dates, times, timestamps and time zone names. The financial source adds daily K line data for stocks, which is the sort of value a seed script for a charting screen needs and which is tedious to fabricate by hand.

The language source is where the project is most unusual

The language and text source is the part of the library that has no obvious equivalent in a general purpose fake data tool. It generates random Chinese characters, random Chinese idioms, and random Tang dynasty poems, alongside random English text and random Chinese short sentences. The idiom generator produces a real four character expression rather than four random characters, which matters if your seed data is going to be rendered in a list of phrases. There is also a pinyin library referenced in the README's table of contents, alongside a JSON library section, and the pinyin capability shows up in the personal source as the pinyin form of a network nickname. For a developer building a Chinese market product, those two libraries are likely the reason to pick this project rather than a generic generator, and for everyone else they are harmless extra weight in a jar the README measures at about 1.2M.

Where common-random is the wrong choice

Three situations argue against it. The first is a test suite that needs adversarial or generated inputs rather than plausible ones. This library produces values that look real, which is the opposite of what you want when the point of the test is to find the boundary case, and a property based testing library exists for that job with a completely different design, generating from a grammar and shrinking failures. The second is a project outside China. The centre of gravity of the data set is Chinese, with provinces and cities, mainland mobile numbers, national ID numbers, QQ, licence plates, the unified social credit code and Tang poems, and while there are English names and international addresses, a western team will get less value from it than from a locale aware generic generator. The third is a pipeline where seed data has to be reproducible across machines. The library gives you random values with no seed parameter visible in the API, so the same test run on two machines produces different data, and the documentation does not describe a mechanism for pinning a seed. That is workable for a demo environment and a problem for a test whose failure you need to reproduce.

Editorial conclusion

Adopt common-random when you need seed data that looks like real Chinese records rather than obvious placeholders, and keep it out of production paths, since the generated identity documents and card numbers are valid only in format. Verify first which groupId your project should use, because the artifact moved from com.apifan.random to io.github.yindz and mixing them in one build is the most likely integration mistake. Then check the version you pin, since 1.1.0 dates from 2024-11-17 and the last push to the repository was on 2026-07-23.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. yindz/common-random on GitHub