nageoffer/12306: a Java 17 and Spring Cloud Alibaba replica of China's railway ticketing system
Officially recommended campus recruitment project built with SpringBoot3, Java17, SpringCloud Alibaba and Vue3, implementing a high-fidelity clone of China Railway 12306's user, ticket-grabbing, order and payment services to help students land jobs.
At a glance
- What is it?
- An Apache-2.0 teaching project that rebuilds the 12306 ticket-booking domain in SpringBoot3, SpringCloud Alibaba and Vue3, with a SpringBoot aggregation service for deployment and a microservice split for study. The value is in the seat-allocation and sharding logic, not in running a real railway.
- Who is it for?
- Adopt it if you want a distributed-systems study target where the interesting parts are seat allocation, sharding-key choice and cache-penetration handling, and you are willing to stand up the middleware environment the project documents before anything starts. Skip it if you need a production ticketing component, a documented installer, or a project whose front end is finished; the README says the front end is still under development and that the console manual will follow.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 8 months ago.
- What is it written in?
- Mainly Java, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- nageoffer/123063,787 ★ · +45
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| nageoffer/12306 | 3.7k | 3.8k |
45 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem nageoffer/12306 solves, and who it is aimed at
This is a study project, not a ticketing provider. The README describes it as a replica of the railway 12306 booking service covering membership, ticket purchase, orders, payment and a gateway, and states plainly that the goal is to let learners pick up distributed-system design, especially around high concurrency. The audience is stated in the repository description: students preparing for campus recruiting, which in the Chinese market means a portfolio project that survives an interview. The README repeats that framing in its FAQ, arguing that even engineers with several years of experience can lift the design patterns into their own work rather than putting the project on a resume.
The interesting consequence is that the project optimises for explainability, not for throughput. A real ticketing system would hide its seat-allocation heuristics behind a service boundary; here the README spells out the six-step fallback for two passengers booking first-class seats with no seat preference: check remaining tickets, find carriages with two free seats, prefer adjacent seats in the same carriage, then non-adjacent seats in the same carriage, then non-adjacent seats in different carriages. That level of detail exists because the code is meant to be read. If you want a library you can import, this is the wrong shape entirely.
Two runnable topologies: aggregation service versus microservices
The repository ships two independent versions, and the README is explicit that they serve different purposes. The SpringBoot aggregation version is described as suitable for testing and deployment, and can be started by launching the aggregation-service and the gateway. The SpringCloud microservice version is described as suitable for learning microservice design, and starts payment, order, user, ticket and gateway services separately. The README warns readers to pick the correct version for their scenario, which is a rare piece of honesty: most teaching repositories pretend one topology covers both.
The microservice split maps onto the domain services named in the README. Around them sit the components listed in the repository topics: Nacos for configuration and discovery, Sentinel for flow control, RocketMQ for messaging, Redis for caching, ShardingSphere for sharding, Elasticsearch, and Prometheus with Grafana for metrics, plus Elastic APM. The top-level layout reflects this, with frameworks/, services/, dependencies/, console-vue/ and checkstyle/ directories, and a Maven wrapper (mvnw) at the root. Nothing in the README claims the two versions are behaviourally identical, so treat the aggregation build as the one to get running first and the microservice build as the one to read.
Installing nageoffer/12306 and starting the aggregation service
The README does not contain install commands inline. It points to a documentation set at nageoffer.com, including a page titled project dependency middleware environment setup and a quick-start page for the backend. Two things are therefore true: the project is not a single-command install, and you should read those pages rather than guess. The repository does give you the build entry point, a Maven wrapper, and the Java version, JDK17, which appears both in the README and in the topic list.
The repository root contains a Maven wrapper, mvnw, alongside pom.xml, and the README names aggregation-service and the gateway as the two processes for the aggregation version. The README does not print the commands themselves, so the run step is: read the quick-start document, bring up the middleware it lists, then start those two services. The front end lives in console-vue/, and the README gives an online demo at 12306.magestack.cn for comparing behaviour. The README states the front end is still under development and that a console operation manual will be published later, so expect to consult the interface documentation page for endpoints rather than a UI walkthrough.
Seat allocation, sharding keys and the cache-penetration argument
The README uses the user service to argue that low-concurrency systems are easy and high-concurrency ones are not, and then lists the questions the code answers. Two of them are worth quoting because they are the substance of the project. First, how to choose a sharding key for user and passenger data, how to introduce sharding on an existing business without an outage, and how to roll back if it goes wrong. Second, how to solve read-request spread when a member can log in by username, phone number or email, so the login path cannot know the shard key in advance. Those are real problems with real trade-offs, and the README frames them as open questions rather than solved ones.
The cache-penetration discussion is the most opinionated passage in the README. It dismisses caching a null value for missing keys and dismisses Bloom filters as having holes, and asks how to solve the problem instead. That is a claim about other people's solutions, not a benchmark, and the README does not present measurements to support it. Read the corresponding document before accepting the framing.
The ticketing side carries its own correction to a common assumption. The README says that buying a Beijing South to Nanjing South ticket does not decrement one segment but three: Beijing South to Jinan West, Beijing South to Nanjing South, and Jinan West to Nanjing South. It also describes dynamic ticket release, where large-station pairs get most of the inventory at first and small-station pairs get a small allocation, with more opened as departure approaches. Whether the implementation matches that description is something you confirm in the code, not in the README.
Where nageoffer/12306 is the wrong tool
The README itself supplies the first limitation: the front end is incomplete. It says the front-end system is still under development, that parts of the business and details are still being adjusted, and that a unified console operation manual will be provided afterwards. Anyone expecting a finished demo will spend their first hour on missing screens.
The second limitation is the middleware footprint. Nacos, Redis, RocketMQ, ShardingSphere, Sentinel, Elasticsearch, Prometheus, Grafana and Elastic APM all appear in the topic list, and the README links a dedicated page for setting up the dependency environment. That page exists because the setup is not trivial. A reader who wants one process and one database will not get it here.
The third is scope discipline. This is a recruiting project by design, and the README's FAQ is about how to write it onto a resume, how interview questions from it are collected, and whether working engineers should read it. If you need a component to embed in a product, the aggregation service is a teaching artefact with no compatibility promise, and the README offers no release history to pin. The repository has no published releases, so there is no versioned artefact to depend on.
Comparing it with a plain Spring Boot booking sample
The obvious alternative is a single-module Spring Boot booking or ticketing sample: one service, one database, maybe Redis for sessions. The difference is not quality, it is what the code lets you practise. A single-module sample cannot show you a sharding migration, because there is nothing to shard. It cannot show read-request spread on login, because there is one datasource. It cannot show a gateway enforcing flow control with Sentinel, because there is no gateway.
The cost of that difference is setup. With a single-module sample you clone, run, and start reading controller code within minutes. With nageoffer/12306 you first satisfy the middleware environment described on the project's own setup page, then choose between the aggregation and microservice topologies, then start two processes for the aggregation path. The payoff is that the questions the README poses, shard-key selection, rollback of a sharding rollout, cache penetration, segment-based inventory decrement, only have answers once the surrounding infrastructure exists. If you already work with these components daily, a single-module sample teaches you nothing new; if you have never wired ShardingSphere or RocketMQ into a booking flow, the extra setup is the point.
Maintenance, licensing and the cost of upgrading
The repository is not archived, and the last push was on 2026-03-12. That is roughly six months before today's date, which is the boundary rather than comfortably inside it, so treat the project as one that has been touched recently but not continuously. The repository has no published GitHub releases, so upgrades are not a matter of moving between tagged versions. In practice you track the main branch, which means an upgrade is a rebase onto whatever the branch looks like now, followed by a re-read of the affected documents, because the README treats the documentation set as part of the deliverable.
The pinning problem follows from that. Without releases, you cannot express a dependency on a known-good state except by committing to a specific commit hash of the repository. For a study project that is acceptable; for anything you intend to deploy and forget, it is not.
The licence is Apache-2.0, and the repository root contains a LICENSE file. Apache-2.0 permits commercial use and modification and requires that you retain the licence and notices, and it includes a patent grant. It does not make the project's dependencies any less subject to their own licences, and the README does not enumerate them. Check the dependency tree yourself if you plan to redistribute a built artefact. This is a description of the licence text, not legal advice.
Editorial conclusion
Adopt it if you want a distributed-systems study target where the interesting parts are seat allocation, sharding-key choice and cache-penetration handling, and you are willing to stand up the middleware environment the project documents before anything starts. Skip it if you need a production ticketing component, a documented installer, or a project whose front end is finished; the README says the front end is still under development and that the console manual will follow. Verify first that you can run the aggregation-service plus gateway path described in the quick-start documents at nageoffer.com, because that is the version the README recommends for testing and deployment, and check the Apache-2.0 LICENSE file in the repository root before you redistribute anything.
Frequently asked questions
Is nageoffer/12306 the real 12306 ticketing system?
No. It is a study project that replicates the railway 12306 booking domain, covering membership, ticket purchase, orders, payment and a gateway, and the README describes its purpose as teaching distributed-system design. The real service is at 12306.magestack.cn only as an online demo for comparison.
Which version of nageoffer/12306 should I start?
The README says the SpringBoot aggregation version is for testing and deployment and can be started with the aggregation-service plus the gateway, while the SpringCloud microservice version is for learning microservice design and starts payment, order, user, ticket and gateway separately. It advises choosing the version that matches your scenario.
Does nageoffer/12306 have a finished front end?
Not according to the README, which states the front-end system is still under development, that some business logic and details are still being adjusted, and that a console operation manual will be provided once it is complete. The Vue3 console lives in the console-vue/ directory.
What middleware does nageoffer/12306 require?
The repository topics list Nacos, Redis, RocketMQ, ShardingSphere, Sentinel, Elasticsearch, Prometheus, Grafana and Elastic APM alongside SpringBoot3, SpringCloud Alibaba and JDK17. The README links a dedicated page for setting up the dependency middleware environment.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/nageoffer-12306)Star history chart for your README
[](https://hysenlabs.com/projects/nageoffer-12306)Was this useful?