{"id":20527447,"url":"https://github.com/dteam-top/clock-seed","last_synced_at":"2025-06-24T14:35:04.955Z","repository":{"id":154035321,"uuid":"165244639","full_name":"DTeam-Top/clock-seed","owner":"DTeam-Top","description":"基于Vert.x和数据库的简单任务队列。","archived":false,"fork":false,"pushed_at":"2019-05-06T08:01:12.000Z","size":38,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-27T18:13:38.760Z","etag":null,"topics":["java","job-queue","vertx"],"latest_commit_sha":null,"homepage":null,"language":"Groovy","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DTeam-Top.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-11T13:01:34.000Z","updated_at":"2022-12-05T05:52:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"cc17b4ee-aa76-47ec-a0cc-47a797a82d3c","html_url":"https://github.com/DTeam-Top/clock-seed","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DTeam-Top%2Fclock-seed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DTeam-Top%2Fclock-seed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DTeam-Top%2Fclock-seed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DTeam-Top%2Fclock-seed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DTeam-Top","download_url":"https://codeload.github.com/DTeam-Top/clock-seed/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248819713,"owners_count":21166529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","job-queue","vertx"],"created_at":"2024-11-15T23:18:55.714Z","updated_at":"2025-04-14T04:22:06.054Z","avatar_url":"https://github.com/DTeam-Top.png","language":"Groovy","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clock Seed\n\nClock模板工程为基于Vert.x和数据库的简单任务队列提供了基础。它目前支持的任务类型（Topic）：\n- topic = ‘SMS’，短消息发送\n- topic = ‘CALLBACK’，回调任务\n\n## 任务相关\n\nClock可以跟[Grails REST SEED](https://github.com/DTeam-Top/grails-rest-seed)工程模板配套使用，后者为前者提供了任务来源。对于每个任务，其属性如下：\n- topic，任务主题，即分类\n- priority，优先级，缺省为5，最高为10，最低为1。优先级高的任务优先执行。\n- body，任务参数，类型为jsonb\n- status，任务状态\n- result，执行结果，类型为jsonb\n- retry，重试次数\n- date_created，任务创建时间\n- last_updated，最后更新时间\n\n任务的产生就是简单地生成上述任务记录，任务记录保存于myjob表中，其结构如下：\n\n~~~\ncreate table myjob (\n    id bigserial not null\n    , topic varchar(10) not null\n    , priority smallint not null\n    , body jsonb not null\n    , status varchar(10) not null\n    , result jsonb\n    , retry smallint not null\n    , date_created timestamp not null\n    , last_updated timestamp not null\n    , primary key (id));\n~~~\n\n对于每个任务，其缺省的重试次数为3次，因此其总的执行次数为4次：1次执行 + 3次重试。\n\n### 回调任务\n\n除topic为‘CALLBACK’的任务外，所有任务都由外部使用者创建。假如任务对应的body包含有callback属性，同时它又不是回调任务，则在它执行完毕之后，将会同时创建回调任务，并且回调任务的body结构如下：\n- source，对应的源任务id\n- callback，回调地址，取自源任务body的callback属性\n- result，源任务的结果\n\n通过这样的机制，将回调也转换成普通的任务对待。\n\n### 任务状态\n\n对于每个任务，其状态如下：\n- CREATED，初始状态\n- PROCESSING，执行状态，在任务执行前，其对应的status会被更改为这个状态\n- SUCCEED，成功结束，任务成功执行完后处于这个状态\n- FAILED，任务失败\n\n状态变化路径见下面几节。\n\n#### CREATED -\u003e PROCESSING -\u003e SUCCEED\n\n这是最普通的情况，任务顺利执行并结束：\n- result记录执行结果。\n- 若任务需要回调通知，即body中包含callback，同时会创建对应的回调任务。\n\n#### CREATED -\u003e PROCESSING -\u003e CREATED\n\n这条路径对应两种可能：\n1. 任务执行失败，但没有超过重试次数。\n1. 任务执行因为某种原因被挂起，成为僵尸任务。这类任务会有另一个重置定时器任务来将任务状态复位。\n\n不论哪种情况，重试次数都会加1。\n\n#### CREATED -\u003e PROCESSING -\u003e FAILED\n\n任务在超出重试次数之后，失败。此时任务的result记录失败原因。\n\n## 使用指南\n\n本工程的基本使用：\n- 扩展AbstractJobHandler开发自己的任务\n- 编写对应的测试\n- 在Launcher中注册任务到对应的topic\n- 打包：gradle shadowjar\n- 书写配置文件\n- 运行：java -jar -Dconf=./conf.tmp build/libs/clock-\\\u003cversion\\\u003e-fat.jar\n\n本工程的配置文件示例如下（Groovy DSL）：\n~~~\npgPool {\n    host = System.getenv(\"JDBC_HOST\") ?: '127.0.0.1'\n    port = System.getenv(\"JDBC_PORT\") ? System.getenv(\"JDBC_PORT\") as int : 5432\n    database = System.getenv(\"JDBC_DATABASE\") ?: 'earth'\n    user = System.getenv(\"JDBC_USER\") ?: 'earth_admin'\n    password = System.getenv(\"JDBC_PASSWORD\") ?: 'admin'\n    maxSize = 5\n    cachePreparedStatements = true\n}\n\nretry = 3\ndelay = 500\nlimit = 100\ntimeout = 8\ncallbackRoot = 'http://localhost:8080'\n\ntopics {\n\n    SMS {\n        key = System.getenv(\"BARN_KEY\") ?: 'mock'\n        password = System.getenv(\"BARN_KS_PASSWORD\") ?: 'mock'\n    }\n\n    CALLBACK {\n        delay = 1000\n        retry = 10\n    }\n\n}\n~~~\n\n其中：\n- pgPool：数据库配置\n- retry：重试次数\n- delay：任务延迟执行时间，ms\n- limit：一次从数据库中取的最大数据条数\n- timeout：僵尸任务时限，hour\n- callbackRoot：回调url的root url\n- topics：任务特定配置\n\n对于retry和delay，任务特定的配置可以覆盖全局配置。假如任务特定配置中没有，则采用全局配置。\n\n上述配置除了pgPool，其余都是可选的，它们对应的缺省值如下：\n- delay：500 ms\n- retry：3\n- limit：100\n- timeout：4 hour\n- callbackRoot：http://localhost:8080\n\n## 代码贡献\n\n本项目使用`codenarc`,`pmd`,`spotbugs`检查项目代码规范，相关的规则配置存储于`config/`目录下，提交代码前使用\n\n```bash\ngradle codenarcMain pmdMain spotbugsMain\n```\n\n执行代码规范检查，并且确保`gradle test`通过测试。\n\nTODO: 找一个好用的git hook插件，可以在提交代码前自动运行代码规范检查\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdteam-top%2Fclock-seed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdteam-top%2Fclock-seed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdteam-top%2Fclock-seed/lists"}