首页   注册   登录
V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
宝塔
V2EX  ›  程序员

向下工作法的一点思考:文档即代码

  •  
  •   banxi1988 · 2018-07-20 07:36:46 +08:00 · 4096 次点击
    这是一个创建于 483 天前的主题,其中的信息可能已经有所发展或是发生改变。

    2006 的时候,amazon CTO 在一篇文章中介绍了向下工作法(或者有也有翻译成向后工作法)

    https://www.allthingsdistributed.com/2006/11/working_backwards.html

    向下工作法,简而言之就是下面的流程:

    1. 先写宣传稿
    2. 再写 FAQ
    3. 再定义用户体验
    4. 再写用户手册

    走完这 4 步之后,对于要做的产品应该是相当的清晰了。

    我看了之后深以为然。

    然后分享我的一个思考:文档即代码

    这一点对于前后端 API 模块的开发来说相当适用。 也就是说,正确良好的工作过程应该是,先写好 API 文档,再通过 API 文档生成前端的 JS/TS 代码。 通过 API 文档生成后端代码。

    前后端的 API 模块都应该遵从这样一个逻辑。

    1. 先写 API 文档。
    2. 通过 API 文档生成 代码,(需要时初始手写代码)
    3. 更新 API 文档
    4. 再根据 API 文档更新前后端代码。
    5. ...

    它带来的好处:

    1. API 文档和前后端的代码,能保持高度一致
    2. 通过代码自动生成基本的代码,减少工作量(大部分的 Domain Model, 和 基本 API 接口请求及响应都应该自动生成)
    3. 方便批量修改。

    API 文档可以采用 Swagger 的文档。

    24 回复  |  直到 2018-07-20 14:29:24 +08:00
        1
    mofe   2018-07-20 07:52:44 +08:00 via iPhone
    其实就是先写测试再写代码……
        2
    johnnie502   2018-07-20 08:06:55 +08:00
    BDD/TDD 请了解一下...
        3
    virusdefender   2018-07-20 08:52:01 +08:00   ♥ 1
        4
    scnace   2018-07-20 09:05:21 +08:00 via Android
    LZ 你要的就是 protobuf 啊 BDD 和 TDD 对业务密集型的应用感觉还是有点勉强 不知道大家是怎么做的
        5
    BearD01001   2018-07-20 09:06:34 +08:00 via iPhone
    亚马逊先发软文再开发了解一下?
        6
    janxin   2018-07-20 09:58:08 +08:00
    @scnace 还好吧,勉强在哪里?
        7
    TommyLemon   2018-07-20 10:25:30 +08:00
    根据文档生成代码,已经有开源方案了
    <img src="http://apijson.org">

    后端接口和文档自动化,前端(客户端) 定制返回 JSON 的数据和结构!
    <img src="https://github.com/TommyLemon/APIJSON">
    创作不易,GitHub 右上角点 Star 支持下吧,谢谢^_^
        8
    Raymon111111   2018-07-20 10:29:03 +08:00
    业务逻辑复杂到一定得有文档

    很常见
        9
    kurtchen   2018-07-20 10:32:42 +08:00
    等写起来会发现文档有时候也不是那么详尽;特别是大型应用
        10
    lastpass   2018-07-20 10:35:10 +08:00 via Android
    然而实际情况是 用户改需求了。
    md 又要改代码又要改文档。
        11
    feverzsj   2018-07-20 10:35:53 +08:00
    文档是不可能写的,项目结束都不可能写文档的,写了也没用,不写的话,公司反而更依赖你
        12
    zhengxiaowai   2018-07-20 10:37:46 +08:00
    理想很好啊,现实很残酷
        13
    lastpass   2018-07-20 10:39:32 +08:00 via Android
    什么,还有一周项目就要交付了。
    我们一行代码都没有写。
    管项目的领导你心里没点笔数吗?
    先做出个 demo 去应付一下吧。
    文档?我 demo 都不一定能写完。
        14
    tingyunsay   2018-07-20 10:42:53 +08:00
    @feverzsj 哈哈,以后跳槽交接的时候能交接半年 o( ̄ε ̄*)
        15
    feverzsj   2018-07-20 10:46:33 +08:00
    @tingyunsay 辞职顶多一个月,公司没有权力不让你跳槽
        16
    zhaogaz   2018-07-20 10:56:09 +08:00
    不知道有什么可思考的,前人的书里面早就写了,多看看书
        17
    ml1344677   2018-07-20 11:04:23 +08:00
    测试驱动开发啊 快速开发原型
        18
    ofooo   2018-07-20 11:10:55 +08:00
    楼主,请问怎么根据文档 api 自动生成代码? api 用什么写?
    还是说只是先有了文档 api 再手工写代码?
        19
    chenyu8674   2018-07-20 11:11:41 +08:00   ♥ 2
    PM:”销售已经跟客户那边把牛逼吹出去了,这需求你们技术必须得做,怎么实现我不管,明天上线“

    向下工作法+敏捷开发,天朝领先世界几十年( doge )
        20
    banxi1988   2018-07-20 11:56:56 +08:00
    @ofooo #18 比如你用 swagger 的文档格式描述 API 的话。
    1 ) swagger 官方网站 本身提供了一系列的工具可以生成各种前后端代码。
    2 )可根据 API 文档 (json 格式,或 yaml 格式)生成(前后端代码)。

    我自己也再做生成前后端代码的脚本。前端脚本基本实现过了。 后端要等等(因为最近没做后端)
        21
    specita   2018-07-20 12:15:33 +08:00
    理想很美好,现实.... 首先你得有一群能实践你想法的队友...
        22
    shyangs   2018-07-20 13:03:42 +08:00
    老外就没遇过需求都讲不清楚,说明天要验收的 PM 呀

    ::doge::
        23
    mcfog   2018-07-20 13:18:57 +08:00 via Android   ♥ 1
    个人更倾向反过来,代码生成文档,毕竟让程序员写代码和让程序员写文档的难度差了不止一个数量级
        24
    A555   2018-07-20 14:29:24 +08:00   ♥ 1
    客户:虽然我想做什么都不知道,但是你必须要满足我。
    我我不知道我要做成什么样啊,不然我找你们干嘛
    关于   ·   FAQ   ·   API   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   2273 人在线   最高记录 5043   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.3 · 30ms · UTC 12:15 · PVG 20:15 · LAX 04:15 · JFK 07:15
    ♥ Do have faith in what you're doing.